Technical details
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.
| Tool | Owned by |
|---|---|
| Vite+ | the workspace root: formatting, linting, task running |
| Nuxt 4 | each application, separately |
| Nuxt UI and Pinia | layer-base, so every layer above it gets them |
| Nuxt Content | layer-site. layer-blog and layer-docs add sections |
| Better Auth | layer-auth |
| Polar | layer-payments |
| Nuxt Email Renderer | layer-email |
| Drizzle ORM | apps/web: schema, migrations, Postgres |
| Varlock | every application, and every layer that reads a variable |
| Vitest | each package, run through Vite+ |
| Cloudflare Workers | each 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.
| Package | Directory | Owns |
|---|---|---|
@app/site | apps/site | the public website, blog, documentation, legal pages and contact form |
@app/web | apps/web | the 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:
export default defineNuxtConfig({
extends: ['@app/layer-site', '@app/layer-blog', '@app/layer-docs'],
})
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.serverPluginSourcesandauth.clientPluginSourcesin the layer's ownnuxt.config.ts, aslayer-paymentsdoes. Don't add them tolayer-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 unit | the owning packages/layer-* package | authentication, payments or email |
| affects only one deployable | that application under apps/ | a product-only page in apps/web/app/pages/ |
| adds a feature that needs a boundary of its own | a new packages/layer-* package | notifications, even if only one application will ever show it |
Commands
| Command | Purpose |
|---|---|
pnpm dev:site | development server for the public website |
pnpm dev:web | development server for the product application |
pnpm dev:prune | remove the local services of checkouts that no longer exist |
vp check | run Oxfmt and Oxlint across the workspace. --fix to repair |
pnpm test | run every test suite |
pnpm typecheck | type-check every package |
pnpm build | build every package |
pnpm ready | the 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:
| Platform | Reaches a service at | Postgres in the main checkout |
|---|---|---|
| macOS with OrbStack | the hostname <service>.<project>.orb.local | postgres.<slug>.orb.local |
| Linux with Docker Engine | the container's IP address | an 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:
| Checkout | apps/web | apps/site |
|---|---|---|
| main | http://web.<slug>.localhost | http://site.<slug>.localhost |
worktree fix-auth-3f9a | http://fix-auth-3f9a.web.<slug>.localhost | http://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
| To | Run, from the checkout |
|---|---|
| free the memory and keep the data | docker compose --project-name <project> stop |
| remove the services of a deleted checkout | pnpm 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.
When the services can't start
The dev commands stop before the server starts, and name the fix, when:
| You see | Fix |
|---|---|
Docker isn't reachable | Start OrbStack on macOS, or Docker Engine on Linux |
Docker runs on <engine>, and … need OrbStack | Install OrbStack, then run docker context use orbstack |
Postgres started, but … is unreachable, on macOS | Check that OrbStack resolves the printed hostname with ping |
Postgres started, but … is unreachable, on Linux | Use 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 80 | Stop the process that lsof -nP -iTCP:80 -sTCP:LISTEN names |
portless can't serve …, below net.ipv4.ip_unprivileged_port_start, on Linux | Run sudo sysctl -w net.ipv4.ip_unprivileged_port_start=80 |
This machine can't resolve …, on Linux | Enable systemd-resolved, or install libnss-myhostname and add myhostname to /etc/nsswitch.conf |
portless isn't answering … over plain HTTP on port 80 | Run 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 process | The 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 PATH | Install Tailscale and put tailscale on PATH (macOS), or run without PORTLESS_FUNNEL |
Tailscale HTTPS is not enabled or Tailscale Funnel is not enabled | Finish 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:
# @import(../../.env.project.schema)
# @import(./node_modules/@app/layer-auth/.env.schema)
# @import(./node_modules/@app/layer-payments/.env.schema)
| File | Holds |
|---|---|
.env.schema | names, types, requiredness and sensitivity. No values |
.env.<context> | the non-secret values for one Runtime Context, plus references to secrets |
.env.infisical | the binding to the secret store for that application |
.env.test | inert fakes, so a clean checkout runs the tests with no credentials |
.env.local | personal 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.
