Build Options
Choose a starter, connect the SDK to an existing app, or use direct HTTP.
Build Options
Choose a starter, add the SDK to your app, or call HTTP directly. You build and host the frontend.
Choose a Build Path
| Starting point | Start with | What the setup provides |
|---|---|---|
| New Next.js app | npm create 01-software-app@0.2.5 | Copies a registered starter, installs dependencies, then offers workspace connection. Run the command to see its starter choices. |
| Existing JavaScript or TypeScript app | npx @01.software/init@0.14.3 | Detects or asks for a target and adds its SDK setup, with prompts for file conflicts. |
| Astro, Remix, SvelteKit, or another framework | npx @01.software/init@0.14.3 | Detects the named frameworks; choose Other for another framework. Prints SDK install and client/server examples, then exits without generating framework wiring. |
| Another language or runtime | API reference | Review each operation's authentication and request requirements for direct HTTP calls. |
The starter command supplies registered Next.js projects, rather than generating an app for any framework or version. Init’s target choices cover Next.js, React with Vite, React with Webpack or CRA, vanilla browser JavaScript, Node.js/Bun/Deno, and Edge. These setup choices do not establish compatibility with every version of those runtimes.
Event starter change in the next init release
The next init release consolidates event starters under --template events,
covering free RSVP/approval and paid admissions. Its default live
requirements remain Events + Ecommerce, plus Customers if customer accounts
are selected. --template events-rsvp exits with code 1 and directs you to
--template events. The interactive chooser and --help omit the retired
starter. Existing apps and previously published init versions are unchanged.
The pinned configurations below are historical observations, not verification
of the next init release. Recheck the published version before switching.
Verified local configurations
These examples were built with Node.js 24.15.0 and npm 11.12.1. This is a tested combination, not a minimum-version promise for every framework.
Observed on 2026-10-20: create 0.2.5 resolves init within ^0.14.3; when adding a missing SDK to an existing app, init installs the latest SDK. Recheck the resolved versions, lockfile and these examples after an init or SDK publication or when setup resolves a different version; the printed --connect command also uses @latest.
| Path | Setup package | SDK | Next.js / React | Verified starters (source bundled in init) |
|---|---|---|---|---|
| New app | create 0.2.5 → init 0.14.3 | 0.65.0 (scaffold pin) | 16.3.8 / 19.2.4 | Ecommerce 0.1.24, Events RSVP 0.1.21 |
| Existing App Router app | init 0.14.3 | 0.65.1 | 16.3.8 / 19.2.4 | Your existing app |
The Quickstart's createClient import and commerce.product.listingPage call work with both SDK versions above. Starter versions describe source included in init, not separate npm packages. Demo builds may require real keys or separate demo configuration: Ecommerce blocks its mock provider in production-mode builds by default. Any mock override used to verify a local demo is not a production setup. A successful demo build does not verify a live workspace connection or customer sign-in. Check the applicable live calls after deploying as described in Deploy.
New-app connection and recovery
Browser authorization connects an existing workspace. Confirm the selected environment: a development key does not isolate local work from that environment’s data or create a Sandbox. The creator writes a credential-free scaffold and completes dependency installation before a verified workspace administrator approves the development app. Only after success does it create .env.local with the existing pk01_ and a new development sk01_. It never uses a Human CLI pat01_ as the app secret.
- With
--no-install, no credential is created. Run the printed install command, then the exact printed--connectcommand. --connectrequires the matching installed, credential-free scaffold. If an existing or ambiguous.env.localblocks connection, preserve it and follow the recovery instructions rather than overwriting it.--auth manualaccepts an existing validpk01_and developmentsk01_pair.--auth skipuses demo data without connecting a workspace. A demo result does not confirm a backend connection.
Existing-app credentials
Init is a separate prompt-driven command and takes no flags. It does not open new-app browser authorization. SDK credential setup is separate from optional AI-tool setup: leaving AI tools unselected still offers Enter manually or Skip for now where credential prompts apply.
| Target | Credential setup |
|---|---|
| Next.js | Manual Publishable Key and development Secret Key, or skip. Default env file: .env.local. |
| React browser targets | Manual Publishable Key, or skip. Default env file: .env. |
| Node.js/Bun/Deno | Manual Publishable Key and development Secret Key, or skip. Default env file: .env. |
| Vanilla browser JavaScript | No key prompt. Replace the generated inline Publishable Key placeholder using your app's configuration. |
| Edge | Manual Publishable Key and development Secret Key, or skip; generated code uses runtime bindings. |
| Manual framework guide | Configure the keys your calls require using your framework’s conventions. |
Before installation or file changes, init validates manual keys and non-empty application credentials in the selected existing env file. It rejects pat01_, malformed values, duplicate declarations, and incomplete server key pairs without changing the existing file. Resolve the reported input problem before retrying.
Credential Boundaries
A Publishable Key can be used in browser code; register each browser origin that will call the workspace. Secret Keys belong only in trusted server code and server configuration. Keep them out of public env variables, browser bundles, command arguments, URLs, and commits. Human CLI PATs stay separate from application keys.
For deployment, issue a separate production Secret Key only when privileged server work requires it. See Authentication & Keys and Integrations & Keys for details.
Deployment Ownership
Use your framework and host’s deployment process, then follow Deploy for credentials, origins, and customer sign-in settings. Next.js-specific variable names do not apply to every runtime.
Continue with Quickstart, the SDK guide, or the API reference.