---
title: "Technical details"
description: "How the monorepo is organised, what each package owns, and the commands you will use most."
canonical_url: "https://nuxtstart.com/docs/getting-started/technical-details"
---

> Index of every page on this site: [llms.txt](https://nuxtstart.com/llms.txt)

Two Nuxt 4 applications and seven Nuxt layers share one [pnpm](https://pnpm.io) workspace, and
[Vite+](https://viteplus.dev) 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](https://nuxtstart.com/docs/getting-started/introduction) lists the features. This table says which
package to open when you want to change one.

<table>
<thead>
  <tr>
    <th>
      Tool
    </th>
    
    <th>
      Owned by
    </th>
  </tr>
</thead>

<tbody>
  <tr>
    <td>
      <a href="https://viteplus.dev" rel="nofollow">
        Vite+
      </a>
    </td>
    
    <td>
      the workspace root: formatting, linting, task running
    </td>
  </tr>
  
  <tr>
    <td>
      <a href="https://nuxt.com" rel="nofollow">
        Nuxt 4
      </a>
    </td>
    
    <td>
      each application, separately
    </td>
  </tr>
  
  <tr>
    <td>
      <a href="https://ui.nuxt.com" rel="nofollow">
        Nuxt UI
      </a>
      
       and <a href="https://pinia.vuejs.org" rel="nofollow">
        Pinia
      </a>
    </td>
    
    <td>
      <code>
        layer-base
      </code>
      
      , so every layer above it gets them
    </td>
  </tr>
  
  <tr>
    <td>
      <a href="https://content.nuxt.com" rel="nofollow">
        Nuxt Content
      </a>
    </td>
    
    <td>
      <code>
        layer-site
      </code>
      
      . <code>
        layer-blog
      </code>
      
       and <code>
        layer-docs
      </code>
      
       add sections
    </td>
  </tr>
  
  <tr>
    <td>
      <a href="https://better-auth.com" rel="nofollow">
        Better Auth
      </a>
    </td>
    
    <td>
      <code>
        layer-auth
      </code>
    </td>
  </tr>
  
  <tr>
    <td>
      <a href="https://polar.sh" rel="nofollow">
        Polar
      </a>
    </td>
    
    <td>
      <code>
        layer-payments
      </code>
    </td>
  </tr>
  
  <tr>
    <td>
      <a href="https://nuxtemail.com" rel="nofollow">
        Nuxt Email Renderer
      </a>
    </td>
    
    <td>
      <code>
        layer-email
      </code>
    </td>
  </tr>
  
  <tr>
    <td>
      <a href="https://orm.drizzle.team" rel="nofollow">
        Drizzle ORM
      </a>
    </td>
    
    <td>
      <code>
        apps/web
      </code>
      
      : schema, migrations, Postgres
    </td>
  </tr>
  
  <tr>
    <td>
      <a href="https://varlock.dev" rel="nofollow">
        Varlock
      </a>
    </td>
    
    <td>
      every application, and every layer that reads a variable
    </td>
  </tr>
  
  <tr>
    <td>
      <a href="https://vitest.dev" rel="nofollow">
        Vitest
      </a>
    </td>
    
    <td>
      each package, run through Vite+
    </td>
  </tr>
  
  <tr>
    <td>
      <a href="https://developers.cloudflare.com/workers/" rel="nofollow">
        Cloudflare Workers
      </a>
    </td>
    
    <td>
      each application, deployed separately
    </td>
  </tr>
</tbody>
</table>

## Repository structure

```text
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.

<table>
<thead>
  <tr>
    <th>
      Package
    </th>
    
    <th>
      Directory
    </th>
    
    <th>
      Owns
    </th>
  </tr>
</thead>

<tbody>
  <tr>
    <td>
      <code>
        @app/site
      </code>
    </td>
    
    <td>
      <code>
        apps/site
      </code>
    </td>
    
    <td>
      the public website, blog, documentation, legal pages and contact form
    </td>
  </tr>
  
  <tr>
    <td>
      <code>
        @app/web
      </code>
    </td>
    
    <td>
      <code>
        apps/web
      </code>
    </td>
    
    <td>
      the signed-in product, <code>
        /auth
      </code>
      
      , <code>
        /admin
      </code>
      
      , billing, the database, APIs and cron work
    </td>
  </tr>
</tbody>
</table>

`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:

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

```ts [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.

```text
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?

<table>
<thead>
  <tr>
    <th>
      If the change...
    </th>
    
    <th>
      Edit...
    </th>
    
    <th>
      Example
    </th>
  </tr>
</thead>

<tbody>
  <tr>
    <td>
      belongs to a feature you may want to move or reuse as a unit
    </td>
    
    <td>
      the owning <code>
        packages/layer-*
      </code>
      
       package
    </td>
    
    <td>
      authentication, payments or email
    </td>
  </tr>
  
  <tr>
    <td>
      affects only one deployable
    </td>
    
    <td>
      that application under <code>
        apps/
      </code>
    </td>
    
    <td>
      a product-only page in <code>
        apps/web/app/pages/
      </code>
    </td>
  </tr>
  
  <tr>
    <td>
      adds a feature that needs a boundary of its own
    </td>
    
    <td>
      a new <code>
        packages/layer-*
      </code>
      
       package
    </td>
    
    <td>
      notifications, even if only one application will ever show it
    </td>
  </tr>
</tbody>
</table>

## Commands

<table>
<thead>
  <tr>
    <th>
      Command
    </th>
    
    <th>
      Purpose
    </th>
  </tr>
</thead>

<tbody>
  <tr>
    <td>
      <code>
        pnpm dev:site
      </code>
    </td>
    
    <td>
      development server for the public website
    </td>
  </tr>
  
  <tr>
    <td>
      <code>
        pnpm dev:web
      </code>
    </td>
    
    <td>
      development server for the product application
    </td>
  </tr>
  
  <tr>
    <td>
      <code>
        pnpm dev:prune
      </code>
    </td>
    
    <td>
      remove the local services of checkouts that no longer exist
    </td>
  </tr>
  
  <tr>
    <td>
      <code>
        vp check
      </code>
    </td>
    
    <td>
      run Oxfmt and Oxlint across the workspace. <code>
        --fix
      </code>
      
       to repair
    </td>
  </tr>
  
  <tr>
    <td>
      <code>
        pnpm test
      </code>
    </td>
    
    <td>
      run every test suite
    </td>
  </tr>
  
  <tr>
    <td>
      <code>
        pnpm typecheck
      </code>
    </td>
    
    <td>
      type-check every package
    </td>
  </tr>
  
  <tr>
    <td>
      <code>
        pnpm build
      </code>
    </td>
    
    <td>
      build every package
    </td>
  </tr>
  
  <tr>
    <td>
      <code>
        pnpm ready
      </code>
    </td>
    
    <td>
      the full local gate: check, test, type-check, then build
    </td>
  </tr>
</tbody>
</table>

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:

```shell
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:

<table>
<thead>
  <tr>
    <th>
      Platform
    </th>
    
    <th>
      Reaches a service at
    </th>
    
    <th>
      Postgres in the main checkout
    </th>
  </tr>
</thead>

<tbody>
  <tr>
    <td>
      macOS with OrbStack
    </td>
    
    <td>
      the hostname <code>
        <service>.<project>.orb.local
      </code>
    </td>
    
    <td>
      <code>
        postgres.<slug>.orb.local
      </code>
    </td>
  </tr>
  
  <tr>
    <td>
      Linux with Docker Engine
    </td>
    
    <td>
      the container's IP address
    </td>
    
    <td>
      an IP such as <code>
        172.18.0.2
      </code>
    </td>
  </tr>
</tbody>
</table>

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](https://github.com/vercel-labs/portless) proxy on port 80:

<table>
<thead>
  <tr>
    <th>
      Checkout
    </th>
    
    <th>
      <code>
        apps/web
      </code>
    </th>
    
    <th>
      <code>
        apps/site
      </code>
    </th>
  </tr>
</thead>

<tbody>
  <tr>
    <td>
      main
    </td>
    
    <td>
      <code>
        http://web.<slug>.localhost
      </code>
    </td>
    
    <td>
      <code>
        http://site.<slug>.localhost
      </code>
    </td>
  </tr>
  
  <tr>
    <td>
      worktree <code>
        fix-auth-3f9a
      </code>
    </td>
    
    <td>
      <code>
        http://fix-auth-3f9a.web.<slug>.localhost
      </code>
    </td>
    
    <td>
      <code>
        http://fix-auth-3f9a.site.<slug>.localhost
      </code>
    </td>
  </tr>
</tbody>
</table>

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

<table>
<thead>
  <tr>
    <th>
      To
    </th>
    
    <th>
      Run, from the checkout
    </th>
  </tr>
</thead>

<tbody>
  <tr>
    <td>
      free the memory and keep the data
    </td>
    
    <td>
      <code>
        docker compose --project-name <project> stop
      </code>
    </td>
  </tr>
  
  <tr>
    <td>
      remove the services of a deleted checkout
    </td>
    
    <td>
      <code>
        pnpm dev:prune
      </code>
    </td>
  </tr>
</tbody>
</table>

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.

<warning>

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.

</warning>

### When the services can't start

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

<table>
<thead>
  <tr>
    <th>
      You see
    </th>
    
    <th>
      Fix
    </th>
  </tr>
</thead>

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

## Environment configuration

[Varlock](https://varlock.dev) 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:

```env-spec [apps/web/.env.schema]
# @import(../../.env.project.schema)
# @import(./node_modules/@app/layer-auth/.env.schema)
# @import(./node_modules/@app/layer-payments/.env.schema)
```

<table>
<thead>
  <tr>
    <th>
      File
    </th>
    
    <th>
      Holds
    </th>
  </tr>
</thead>

<tbody>
  <tr>
    <td>
      <code>
        .env.schema
      </code>
    </td>
    
    <td>
      names, types, requiredness and sensitivity. No values
    </td>
  </tr>
  
  <tr>
    <td>
      <code>
        .env.<context>
      </code>
    </td>
    
    <td>
      the non-secret values for one Runtime Context, plus references to secrets
    </td>
  </tr>
  
  <tr>
    <td>
      <code>
        .env.infisical
      </code>
    </td>
    
    <td>
      the binding to the secret store for that application
    </td>
  </tr>
  
  <tr>
    <td>
      <code>
        .env.test
      </code>
    </td>
    
    <td>
      inert fakes, so a clean checkout runs the tests with no credentials
    </td>
  </tr>
  
  <tr>
    <td>
      <code>
        .env.local
      </code>
    </td>
    
    <td>
      personal overrides, never committed
    </td>
  </tr>
</tbody>
</table>

`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`:

```ts
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](https://nuxtstart.com/docs/reference/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](https://nuxtstart.com/docs/deployment/pipeline) for what each event deploys.
[Resources](https://nuxtstart.com/docs/deployment/resources) covers the resources behind the bindings, and
[Database](https://nuxtstart.com/docs/reference/database) covers migration policy.

## Sitemap

See the full [sitemap](https://nuxtstart.com/sitemap.md) for all pages.
