Prepare a workspace

Sign up at 01.software and complete onboarding if you do not have a workspace. Onboarding creates a Project and its LIVE environment. Select the actual environment you intend to use and its keys; a Project name is not a credential. A local development key does not isolate data or automatically create a Sandbox. Choose Ecommerce for this example; Feature Planning explains other choices. If someone else manages your workspace, ask its administrator to authorize the new app or provide the application keys needed for your existing app.

Connect your app

New app

Run the starter command and choose from its registered Next.js starters:

npm create 01-software-app@0.2.5

Use browser authorization to connect an already-existing workspace. The command creates the scaffold and installs dependencies without credentials, then asks a verified workspace administrator to approve the development app. After approval succeeds, it creates .env.local with the workspace's Publishable Key and a new development Secret Key. You do not need to download an env file for this route.

Existing app

Run this in your existing project with a package.json:

npx @01.software/init@0.14.3

Follow the generated setup for your target. Init uses prompts for manual application keys or a credential-free skip; it does not open the new-app browser authorization flow. For frameworks it does not wire, it prints SDK installation and client/server examples instead. See Build Options for target details and skipped-install recovery.

For manual setup, copy the keys from onboarding or request them from your workspace administrator. If key issuance fails, retry from the completion screen or issue a key in Console. Enter application keys through init’s prompts; for manual wiring, use environment variables such as these:

NEXT_PUBLIC_SOFTWARE_PUBLISHABLE_KEY=pk01_...
SOFTWARE_PUBLISHABLE_KEY=pk01_...
# Only for privileged server operations; not needed for this product count
SOFTWARE_SECRET_KEY=sk01_...

Only configure SOFTWARE_SECRET_KEY if your server operations need it. Use the filename your app reads (.env.local for Next.js). Do not overwrite the file created by successful new-app browser authorization. The Secret Key is shown once; if lost, issue a replacement from API Keys in Console.

Show your first result

This is a Next.js App Router Server Component example. In a new app, use app/page.tsx and open /. In an existing App Router app, preserve your homepage: add the example at an unused route such as app/catalog-example/page.tsx and open /catalog-example, or integrate the call into an existing Server Component without replacing its content. The code title below shows the new-app location. Start the app with its own development command. For Pages Router or another framework, follow its setup and adapt the same SDK helper rather than copying this page unchanged.

This server call sends no browser Origin. If you call from browser code instead, register that origin first under Integrations & Keys.

The explicit dynamic rendering below calls the catalog on each page request instead of prerendering a product count during next build. Set NEXT_PUBLIC_SOFTWARE_PUBLISHABLE_KEY in the build environment; changing that public value after a production build requires rebuilding the app.

import { createClient } from '@01.software/sdk'

export const dynamic = 'force-dynamic'

export default async function Page() {
  const client = createClient({
    publishableKey: process.env.NEXT_PUBLIC_SOFTWARE_PUBLISHABLE_KEY!,
  })
  const { cards } = await client.commerce.product.listingPage({ limit: 10 })

  return (
    <main>
      <h1>Catalog</h1>
      <p>{cards.length} published products loaded.</p>
    </main>
  )
}

You should see Catalog and a product count. 0 published products loaded. is a successful empty result; you can continue without creating a product. A populated catalog shows a non-zero count. This call needs only the Publishable Key.

For privileged server operations, see the SDK guide and Authentication.