Getting Started

Technical details

How the monorepo is organised, what each package owns, and the commands you will use most.

Two Nuxt 4 applications and seven Nuxt layers share one pnpm workspace, and Vite+ runs the workspace tasks. There is no root Nuxt application. Nothing scans packages/ or orders it for you. Each application names the layers it wants.

Who owns what

The Introduction lists the features. This table says which package to open when you want to change one.

ToolOwned by
Vite+the workspace root: formatting, linting, task running
Nuxt 4each application, separately
Nuxt UI and Pinialayer-base, so every layer above it gets them
Nuxt Contentlayer-site. layer-blog and layer-docs add sections
Better Authlayer-auth
Polarlayer-payments
Nuxt Email Rendererlayer-email
Drizzle ORMapps/web: schema, migrations, Postgres
Varlockevery application, and every layer that reads a variable
Vitesteach package, run through Vite+
Cloudflare Workerseach application, deployed separately

Repository structure

apps/
  site/                # public website: landing, legal, contact form, blog, docs
  web/                 # signed-in product: dashboard, account settings, billing, /auth, /admin
packages/
  layer-base/          # UI primitives, composables, shared utils and schemas
  layer-email/         # transactional email templates and sending utilities
  layer-site/          # website shell, content foundation, contact feature
  layer-blog/          # blog content section and pages
  layer-docs/          # documentation content section and presentation
  layer-payments/      # Polar products, orders, subscriptions and webhooks
  layer-auth/          # Better Auth wiring, account settings, user administration
tooling/               # repository tooling only; no application may depend on it
scripts/               # workspace-level scripts only
docs/                  # architecture decision records and agent-facing notes
package.json           # root commands and package manager metadata
pnpm-workspace.yaml    # workspace packages and the shared dependency catalog
vite.config.ts         # Vite+ formatting, linting and staged-file tasks

The root owns workspace orchestration. Application code belongs to an application. Feature code belongs to the layer that owns it.

The two applications

Each application has its own package.json, nuxt.config.ts, environment schema and test setup. They run and deploy independently.

PackageDirectoryOwns
@app/siteapps/sitethe public website, blog, documentation, legal pages and contact form
@app/webapps/webthe signed-in product, /auth, /admin, billing, the database, APIs and cron work

apps/web keeps its pages in apps/web/app/pages. The product surface belongs to the application, not to a layer of its own.

An application extends only the layers it uses directly:

apps/site/nuxt.config.ts
export default defineNuxtConfig({
  extends: ['@app/layer-site', '@app/layer-blog', '@app/layer-docs'],
})
apps/web/nuxt.config.ts
export default defineNuxtConfig({
  extends: ['@app/layer-payments', '@app/layer-auth'],
})

layer-base and layer-email are missing from both lists on purpose. The layers that need them declare them, so Nuxt pulls them in transitively.

How the layers fit together

Every layer is a workspace package with its own code, config, modules, tests and exports. You should be able to drop a layer into another Nuxt project without copying files out of this repository.

layer-site     -> layer-email, layer-base
layer-blog     -> layer-site
layer-docs     -> layer-site
layer-auth     -> layer-email, layer-base
layer-payments -> layer-auth, layer-email, layer-base

The arrows are extends relationships. Each one is written twice: as a workspace:* dependency in package.json, and as an entry in nuxt.config.ts. The manifest is what the workspace tooling reads. extends is what sets Nuxt's layer resolution order.

Ownership rules:

  • A layer declares the Nuxt modules its own code needs.
  • Its CSS, runtime defaults, route rules, auto-import directories and type templates live with it.
  • So do its components, composables, stores, server handlers, schemas and email templates.
  • So do its Better Auth plugins. List them under auth.serverPluginSources and auth.clientPluginSources in the layer's own nuxt.config.ts, as layer-payments does. Don't add them to layer-auth, which must work without the layers that extend it.
  • Cross-layer imports go through the package name and an exported subpath, like @app/layer-base/shared/utils/constants.
  • Inside a layer, use relative imports. Never a self-referencing alias.

A feature layer may depend on the base layer. Sibling layers must not reach into each other through relative paths.

Where should a change live?

If the change...Edit...Example
belongs to a feature you may want to move or reuse as a unitthe owning packages/layer-* packageauthentication, payments or email
affects only one deployablethat application under apps/a product-only page in apps/web/app/pages/
adds a feature that needs a boundary of its owna new packages/layer-* packagenotifications, even if only one application will ever show it

Commands

CommandPurpose
pnpm dev:sitedevelopment server for the public website
pnpm dev:webdevelopment server for the product application
pnpm dev:pruneremove the local services of checkouts that no longer exist
vp checkrun Oxfmt and Oxlint across the workspace. --fix to repair
pnpm testrun every test suite
pnpm typechecktype-check every package
pnpm buildbuild every package
pnpm readythe full local gate: check, test, type-check, then build

There is no root dev command on purpose. It would have to pick one of the two applications for you.

vp check is not a replacement for nuxt typecheck. Type checking runs as each application's own task, because it needs Nuxt's generated types and auto-imports. Ask for one package by name:

vp run @app/site#typecheck
vp run @app/web#build

Git hooks live in .vite-hooks/. Before a commit they scan the staged diff for resolved secrets, then run the staged tasks from vite.config.ts. The commit-message hook runs commitlint.

Local services

Each worktree of a clone runs its own Postgres and Mailpit, declared in compose.yml at the repository root. pnpm dev:web and pnpm dev:site start them through scripts/localStack.ts before the server starts. A worktree therefore migrates its own database, and its mail lands in its own inbox. This holds for a worktree from any tool: Git, Claude Code, Codex, or another harness.

Two separate clones of one project are both main checkouts and share the <slug> stack. Use a worktree, not a second clone, for a separate database.

The checkout decides the Docker Compose project name. No service publishes a host port, so checkouts and projects never compete for one. Your machine reaches each service on its own port instead:

PlatformReaches a service atPostgres in the main checkout
macOS with OrbStackthe hostname <service>.<project>.orb.localpostgres.<slug>.orb.local
Linux with Docker Enginethe container's IP addressan IP such as 172.18.0.2

A container's IP can change when it restarts. The dev command reads it again on every run.

A worktree's Compose project is <slug>-<folder>-<hash>, such as <slug>-fix-auth-3f9a. The hash comes from the worktree's path, so two worktrees with the same folder name get different projects. Moving a worktree's folder changes the hash, and the moved worktree starts with an empty database.

The dev command hands the application DATABASE_URL and NUXT_EMAIL_DEV_SMTP_HOST as process environment variables. These outrank every env file, so a .env.local copied from another checkout can't point a worktree at that checkout's database.

Application hostnames

Each checkout also serves its applications at its own hostnames, through the portless proxy on port 80:

Checkoutapps/webapps/site
mainhttp://web.<slug>.localhosthttp://site.<slug>.localhost
worktree fix-auth-3f9ahttp://fix-auth-3f9a.web.<slug>.localhosthttp://fix-auth-3f9a.site.<slug>.localhost

The worktree label is the part of the Compose project after the slug. Each server gets a free port behind the proxy, so you never open a port yourself. Separate hostnames keep each checkout's sign-in apart, because browsers share cookies across ports on one host.

The dev command also hands the application NUXT_PUBLIC_APP_BASE_URL and, for apps/web, NUXT_PUBLIC_APP_WEBSITE_BASE_URL. Both point at the same checkout's hostnames, whether or not the other application is running.

The proxy serves plain HTTP, so it never asks for sudo or installs a certificate. It's shared by every project on your machine and starts on the first dev command. A second pnpm dev:web in a checkout whose apps/web already runs stops without touching the running server.

Stop or remove services

ToRun, from the checkout
free the memory and keep the datadocker compose --project-name <project> stop
remove the services of a deleted checkoutpnpm dev:prune

Removing a worktree doesn't remove its services. pnpm dev:prune removes the containers, network and database volume of every checkout of this project whose folder no longer exists. pnpm dev:web and pnpm dev:site run the same pruning before they start, so stale services disappear on your next run.

The pruning treats a missing folder as a deleted checkout. A worktree on a disconnected drive loses its database the next time you run a dev command.

When the services can't start

The dev commands stop before the server starts, and name the fix, when:

You seeFix
Docker isn't reachableStart OrbStack on macOS, or Docker Engine on Linux
Docker runs on <engine>, and … need OrbStackInstall OrbStack, then run docker context use orbstack
Postgres started, but … is unreachable, on macOSCheck that OrbStack resolves the printed hostname with ping
Postgres started, but … is unreachable, on LinuxUse Docker Engine running natively. Docker Desktop and rootless Docker don't let the host reach container IPs
Local services run on macOS … or Linux …Windows isn't supported
portless can't serve local apps on port 80, Another process may hold port 80Stop the process that lsof -nP -iTCP:80 -sTCP:LISTEN names
portless can't serve …, below net.ipv4.ip_unprivileged_port_start, on LinuxRun sudo sysctl -w net.ipv4.ip_unprivileged_port_start=80
This machine can't resolve …, on LinuxEnable systemd-resolved, or install libnss-myhostname and add myhostname to /etc/nsswitch.conf
portless isn't answering … over plain HTTP on port 80Run pnpm exec portless proxy stop, then the dev command again
This checkout's apps/<app> already runs at …Use the running server, or reach it with nuxt curl from apps/<app>. If none runs, run pnpm exec portless proxy stop
"<hostname>" is already registered by a running processThe same, caught while that server was still starting. Don't pass --force: it stops the running server
Tailscale's port 443, which your Polar webhook endpoint names, is held by …Stop the Funnel it names, or the dev command that started it. tailscale funnel --https=443 off stops a background one
PORTLESS_FUNNEL=1 needs the Tailscale CLI, and `tailscale` is not on PATHInstall Tailscale and put tailscale on PATH (macOS), or run without PORTLESS_FUNNEL
Tailscale HTTPS is not enabled or Tailscale Funnel is not enabledFinish the one-time Tailscale setup

Environment configuration

Varlock resolves every variable. Layers declare what their code reads, applications supply the values, and APP_RUNTIME_CONTEXT decides which values load.

Each application owns an .env.schema. It declares that application's variables, imports the schema of every layer it composes, and imports your project's identity from the repository root:

apps/web/.env.schema
# @import(../../.env.project.schema)
# @import(./node_modules/@app/layer-auth/.env.schema)
# @import(./node_modules/@app/layer-payments/.env.schema)
FileHolds
.env.schemanames, types, requiredness and sensitivity. No values
.env.<context>the non-secret values for one Runtime Context, plus references to secrets
.env.infisicalthe binding to the secret store for that application
.env.testinert fakes, so a clean checkout runs the tests with no credentials
.env.localpersonal overrides, never committed

local is the default and has no value file. It loads .env.development instead. Set APP_RUNTIME_CONTEXT before you run anything that deploys: a varlock-wrangler deploy without it resolves local and deploys a stray <slug>-<app>-local Worker carrying development's values.

Load Varlock before you read ENV:

import 'varlock/auto-load'
import { ENV } from 'varlock/env'

varlock/auto-load covers nuxt.config.ts too, so Nuxt commands stay unwrapped. You never need varlock run -- in front of them.

Two files sit at the repository root, and they are not the same thing. .env.schema is for repository tooling; varlock resolves from the working directory and does not walk up, so nothing under apps/ or packages/ can read it. .env.project.schema beside it holds your project's identity, and both applications reach it by the import above rather than by resolution. Project identity is what it declares and what derives from it.

Deployment shape

apps/site and apps/web deploy as separate Cloudflare Workers, and GitHub Actions is what deploys them. Only apps/web has a database. The deploy workflow applies its migrations. A plain build never does.

Read Deploy pipeline for what each event deploys. Resources covers the resources behind the bindings, and Database covers migration policy.

Copyright © 2026