Get started

This guide helps you run the next-hydra demo locally using the default provider stack: commercetools, Contentstack, and WorkOS.

Before you begin

You will need:

• Node.js and pnpm
• a new commercetools project
• a new Contentstack stack
• a new WorkOS app

This starter is a monorepo, so we recommend pnpm for both scaffolding and local development.

The goal is simple: get the demo running locally with the same provider path used by the starter.

Step 1. Scaffold the project

Use create-next-hydra to scaffold a new workspace.

pnpm create next-hydra@latest

Follow the CLI prompts to scaffold the project in a new directory. Once the code is in place, you can provision the services the demo expects.

Step 2. Create your commercetools project

Start by creating a commercetools trial account here: commercetools free trial. It is the default commerce integration used throughout the repo, including product, cart, and store services.

When commercetools asks how to initialize the new project, choose the sample dataset option and select B2B: Heavy Machinery. This is the recommended dataset for next-hydra because it is what powers the demo experience.

What you should do in commercetools:

1. Create a new commercetools project from the trial account.
2. Choose Sample dataset instead of an empty project.
3. Select B2B: Heavy Machinery.
4. Enable Product projection search in the Merchant Center by navigating to Settings > Project settings > Storefront Search—without it, product search in the app will not work. See Product projection search.
5. Create an API client for the storefront using the Scopes from Frontend B2B template, and add the Custom objects scope (in addition to every scope that template already includes).
6. Copy the project key, client id, client secret, region, and scopes into your local env file.

You will need these values from commercetools:

Step 3. Set up Contentstack

Create a Contentstack trial account here: Contentstack free trial. Contentstack powers the default CMS integration, content blocks, draft mode, and live preview flow in the repo.

This part of the setup is still a work in progress in the docs. For now, create the minimum content model needed by the starter:

1. Create a new Contentstack stack.
2. Create a Landing Page content type.
3. Create a Navigation content type.
4. Create an environment for local development.
5. Generate delivery and preview tokens for that environment.

The schema export and a fuller Contentstack bootstrap flow will be documented separately.

You will need these values from Contentstack:

Step 4. Configure WorkOS

next-hydra uses WorkOS as the default auth path. The web app is wired to WorkOS today.

Create a WorkOS app, configure your local redirect URI, and collect these values:

WorkOS is the supported setup path for this page because it matches the current apps/web wiring.

Clerk adapter option

The repo also includes a Clerk adapter package, but swapping auth providers is not just an env change. It requires changing the app wiring from the WorkOS package to the Clerk package

Step 5. Add your environment variables

Copy apps/web/.env.example to apps/web/.env.local and apps/api/.env.example to apps/api/.env.local, then fill in your values.

The apps use t3-env (@t3-oss/env-nextjs); if a required value is missing or invalid, the app will not start. Run each app to confirm everything is set.

Step 6. Run the demo locally

Once the required environment variables are in place, install dependencies and start the workspace.

pnpm install
pnpm turbo dev --filter=web

This starts only the web app, which is the fastest way to verify the demo locally.

Open http://localhost:3001 to verify the storefront boots with your configured providers.

What next?