Getting Started

Local setup

Get both applications running on your machine, in the order their pieces depend on each other.

By the end of this page you have two applications running on your machine: the public website at http://site.<slug>.localhost, and the signed-in product at http://web.<slug>.localhost. The product talks to a Postgres database in Docker, and the email it sends lands in a local inbox instead of a real one. Nothing here deploys anything.

This is stage 1, and local is the only Runtime Context it sets up. Deploying development and Adding pull request previews come next, each on its own and in either order. Adding staging adds an optional pre-production context, and Going to production comes last, once the application and its name are final.

Work through the steps in order. Each one depends on the one before it, and the errors you get from skipping ahead name a missing value rather than the step you skipped.

Set aside an hour the first time. Most of it is creating accounts, not writing code.

Prerequisites

You needWhere the version comes from
Node.jsThe devEngines.runtime field in the root package.json
pnpmThe devEngines.packageManager field in the root package.json
GitAny recent version
gh, signed in with gh auth loginAny recent version
ShellCheckThe SHELLCHECK_VERSION in the Lint shell scripts and workflows step of .github/workflows/deploy.yml
actionlintThe ACTIONLINT_VERSION in the Lint shell scripts and workflows step of .github/workflows/deploy.yml
OrbStack on macOS, or Docker Engine on LinuxAny recent version. Runs Postgres and the local mail inbox
An Infisical accountFree plan. Holds your credentials

On Linux, the local proxy needs port 80 without root. Allow it with sudo sysctl -w net.ipv4.ip_unprivileged_port_start=80, and write the same setting to a file in /etc/sysctl.d/ to keep it after a reboot. Linux also has to resolve *.localhost to loopback, which getent hosts web.x.localhost checks. If it prints nothing, enable systemd-resolved, or install libnss-myhostname and add myhostname to the hosts line of /etc/nsswitch.conf.

Social sign-in and payments also need a Google Cloud project, a GitHub OAuth app, and a Polar sandbox account. You can skip any of the three today and add it later — the step below on which features you're wiring up says what to put in the meantime. Locally, only GitHub sign-in works: Google refuses local redirect URIs, so you test it once development deploys.

Get the code

Your project starts from NuxtStart's published branch, the Published Tree: NuxtStart's source with its own values and migration history removed. Don't fork NuxtStart or copy its default branch — both hand you NuxtStart's development, which carries them.

Create an empty repository and pull published into its development branch:

# Empty on purpose: a README or license commit makes the first push fail
gh repo create <your-account>/<your-repo> --private

mkdir <your-repo> && cd <your-repo>
git init --initial-branch=development
git remote add origin https://github.com/<your-account>/<your-repo>.git
git remote add nuxtstart https://github.com/NuxtStart/NuxtStart.git
git pull nuxtstart published
git push --set-upstream origin development

The nuxtstart remote is how you pull NuxtStart's later changes — see Getting updates.

Everything on this page, and every deploy stage before production, happens on development. It's your repository's default branch because it's the first one you push, and it's the branch that gives you a live URL.

A push is safe. Until your repository holds a Cloudflare API token, the deploy gate skips every deploy and the run stays green. Connect the repository to Cloudflare adds the token, and from then on a Runtime Context with an empty value fails its run, naming the key. See When a deploy is skipped.

Name your project

Your copy ships with these values empty in .env.project.schema, at the root of the repository. Both applications read this file, and each value is required, so neither application installs or runs on your machine until every one is set.

.env.project.schema
PROJECT_SLUG=acme
PROJECT_DISPLAY_NAME=Acme
PROJECT_DESCRIPTION="A CRM for small agencies, with pipelines, invoicing and client portals."
PROJECT_ZONE=acme.com

PROJECT_SLUG is the lowercase name inside every Worker, bucket, and database you'll create, and its type rejects a slug that can't become one — Project identity has the shape. PROJECT_DISPLAY_NAME appears in page titles, transactional email, and social images. PROJECT_DESCRIPTION is one sentence saying what your product is, in at most 160 characters. It becomes the website's meta description and the summary at the top of its llms.txt. PROJECT_ZONE is the DNS zone you own; your sending domains hang off it.

There's one more item, PROJECT_DOMAIN, and you can leave it alone for now. It defaults to your zone, and only production reads it. Project identity is the full picture — what derives from these, and what stays yours to write.

Decide which features you're wiring up today

Email and password sign-in, the database, and transactional email need no provider account. Social sign-in and payments do, and each one is a layer you can leave unconfigured for now:

FeatureLayerKeys it asks for
Google sign-in@app/layer-authGOOGLE_CLIENT_ID, GOOGLE_CLIENT_SECRET
GitHub sign-in@app/layer-authGITHUB_CLIENT_ID, GITHUB_CLIENT_SECRET
Payments@app/layer-paymentsPOLAR_ACCESS_TOKEN, POLAR_WEBHOOK_SECRET

Every key is required, so put a stand-in such as unused in the ones you're skipping. The two later steps say which file or folder each key goes in. apps/web starts either way, and only the feature that reads the key fails when you first use it — the Google button, or a checkout.

A stand-in deploys like any other value, so the feature stays broken in every context you deploy it to. Add the real values whenever you're ready with Set up sign-in and payments.

Set up your secret store

Both applications read their credentials from Infisical, and neither installs nor starts until it can. Follow Set up your secret store, then come back here.

You're ready to continue when you have:

  • Your own project ID in apps/web/.env.infisical and apps/site/.env.infisical
  • A machine identity's client ID and secret in apps/web/.env.local and apps/site/.env.local
  • The development environment's /local folder filled in for the apps/web project

Fill in the values that are yours

The values that belonged to NuxtStart ship empty in your copy, and each one is required. These are the ones you can choose now, so put them in the committed development files:

apps/web/.env.development
GOOGLE_CLIENT_ID=<your Google client ID>
GITHUB_CLIENT_ID=<your GitHub client ID>
apps/site/.env.development
NUXT_PUBLIC_CONTACT_EMAIL=hello@example.com

That's a short list because the Worker name, the bucket, the database, and the sending domain aren't in these files at all. They're built from the values you set above, so renaming your project renames all of them. Project identity lists which names derive and which stay yours.

Your sending domain is one of the derived ones, <slug>-<app>-local.<zone> while you work locally. Mailpit catches that mail instead of delivering it, so nothing has to be onboarded yet. Email will not send until you onboard a domain covers onboarding the deployed ones for real delivery.

Skipping Google or GitHub sign-in? Put your stand-in in that provider's client ID.

Leave the empty origins in these files alone. They're deployed origins, yours to write at the step that pushes development, and the next step gives your machine its own.

Create your local origin overrides

.env.development.local overrides keys that .env.development already sets. Environment values explains the split. Create one per application, with your slug in place of <slug>:

apps/web/.env.development.local
NUXT_PUBLIC_APP_BASE_URL=http://web.<slug>.localhost
NUXT_PUBLIC_APP_WEBSITE_BASE_URL=http://site.<slug>.localhost
apps/site/.env.development.local
NUXT_PUBLIC_APP_BASE_URL=http://site.<slug>.localhost

These serve the commands that don't start a server, such as pnpm install, db:generate and typecheck, which otherwise stop on the empty origins. The dev commands hand each application its own origins, its database, and its inbox in process env, which outranks every env file, so a worktree still gets its own URLs.

Install dependencies

pnpm install

This also prepares both applications, which generates the types your editor needs. Preparing resolves every value the steps above set, so it stops on any that's still missing and names it. Troubleshooting says where each one goes.

Generate your first migration

Your copy ships the database schema and no migration history. Migration publication explains why.

cd apps/web
pnpm db:generate

Commit what it writes. You own that history from here. The dev server applies pending migrations when it starts, so there's no separate apply step locally.

Run both applications

Make sure OrbStack, or Docker Engine on Linux, is running. Then use two terminals, one command each. There's no root dev command, because it would have to choose one of the two applications for you.

pnpm dev:site
pnpm dev:web

Before either server starts, the command starts this checkout's Postgres and Mailpit inbox in Docker and waits until they're ready. The first run downloads both images. Each command prints the database's connection string, the inbox's address, and both applications' URLs, whichever one it starts. On macOS, pnpm dev:web prints this:

Postgres  postgres://postgres:postgres@postgres.<slug>.orb.local:5432/web
Mailpit   https://mailpit.<slug>.orb.local
Web       http://web.<slug>.localhost
Site      http://site.<slug>.localhost

The applications are served through portless, a local proxy on port 80, so open the printed URL of the application you started rather than a port.

Mailpit catches every email the product sends, so nothing leaves your machine. The containers keep running after you stop the server. Local services covers worktrees and how to stop or remove them.

Check that it worked

  1. Sign up at http://web.<slug>.localhost/auth/sign-up with your own address, such as <user>@<org>.com. Nothing seeds a local account.
  2. Open the Mailpit address the command printed and read the verification email.
  3. Open http://site.<slug>.localhost/docs and confirm the website serves this page.

Optional: receive Polar webhooks locally

Skip this unless you're testing payment events after checkout, such as renewals, cancellations, or refunds. Everything else runs without it. Polar delivers the local webhook through Tailscale Funnel, which needs a one-time setup:

  1. Install Tailscale. The free plan includes Funnel. Make sure tailscale runs in a terminal. On macOS, install the app's CLI from its Settings (Standalone), or put a wrapper for /Applications/Tailscale.app/Contents/MacOS/Tailscale on PATH (App Store). A shell alias isn't enough, because the dev command doesn't read it.
  2. Sign in to Tailscale.
  3. Join your machine to your tailnet:
    Terminal
    tailscale up
    
  4. In the admin console, open DNS and select Enable HTTPS under HTTPS Certificates.
  5. In Access controls, give every tailnet member the funnel node attribute. Add this excerpt to the policy file, or see Funnel's requirements to target fewer devices:
    policy.hujson (excerpt)
    "nodeAttrs": [{ "target": ["autogroup:member"], "attr": ["funnel"] }]
    

Then register the endpoint once, as Receive webhooks locally describes. If a step is missing, PORTLESS_FUNNEL=1 pnpm dev:web stops and names it.

Troubleshooting

Read the name in the error first. It names the value that's missing, which is rarely the thing you were working on when it broke.

What you seeWhat to fix
Infisical authentication is requiredThe client ID and secret in that application's .env.local
projectId is requiredYour Infisical project ID in that application's .env.infisical
Value is required but is currently emptyThe key it names: identity in .env.project.schema, an origin in .env.development.local, a client ID or contact address in .env.development
A regex or length error on PROJECT_SLUGA slug outside the shape in Project identity
An invalid URL or emailA typo, or a stand-in in a typed key. Only the feature keys take a stand-in
An error naming a single secretThat key is missing from the /local folder in Infisical
Docker isn't reachable or any other ✖ line before the server startsWhen the services can't start
PROJECT_SLUG is empty in .env.project.schemaThe project name from Name your project
Sign-up works but no email arrivesYou're reading another checkout's inbox. Open the Mailpit address this checkout's command printed
Links to /docs and /blog don't loadStart the website too, with pnpm dev:site in the same checkout

Next steps

Both applications run, so the rest of this section is about making the project yours:

Two more if you skipped something above:

Copyright © 2026