Project structure
What you'll have afterwards:
- You know which file to open to change a module option, the landing page or who counts as an admin.
- You know where your own pages, components and API routes go.
The workspace starter creates your workspace: a pnpm workspace with one Nuxt 4
host app in apps/web. This page tours its files.
Prerequisites
A project created in Installation.
At a glance
my-app/
package.json root scripts: dev, build, preview, lint, lint:fix, typecheck, test, prepare:env,
db:generate, db:migrate, clean
pnpm-workspace.yaml apps/* and packages/*
AGENTS.md conventions for you and your coding agents
scripts/prepare-env.mjs creates the apps' .env files and fills in empty secrets
packages/eslint-config/ shared lint config for packages you add
apps/web/
nuxt.config.ts the modules and their options
app/pages/index.vue the landing page
server/plugins/authorization-roles.ts makes verified NUXT_ACL_ADMINS addresses admins
server/db/migrations/sqlite/ the database schema, committed
modules/libsql-binding.ts puts the sqlite driver's native binding in the server build
The workspace root
apps/web. pnpm resolves workspace dependencies relative to
the root.The root package.json scripts run the app through --filter ./apps/web:
| Script | What it does |
|---|---|
pnpm dev | Starts the apps/web dev server. |
pnpm build, pnpm preview | Builds every workspace, or previews apps/web. |
pnpm lint, pnpm lint:fix | Runs ESLint in every workspace. |
pnpm typecheck, pnpm test | Runs them in every workspace. |
pnpm prepare:env | Creates each app's .env (Configuration). |
pnpm db:generate, pnpm db:migrate | Generates and applies migrations (Database). |
pnpm clean | Runs each workspace's clean script, then removes the root node_modules and .data. |
To run something in one app, stay at the root and use --filter:
pnpm --filter ./apps/web <command>
pnpm-workspace.yaml lists apps/* and packages/*. Put your own shared code in packages/. The starter's
packages/eslint-config is the lint config its apps use.
AGENTS.md holds the project's conventions for you and for coding agents. Keep it up to date as the project changes.apps/web
The host app uses the Nuxt 4 layout: app code is under app/ and server code under server/.
| Path | Purpose |
|---|---|
nuxt.config.ts | The modules the app installs and their options. See Configuration. |
app/pages/index.vue | The landing page. Replace it with your own. |
server/plugins/authorization-roles.ts | Adds the admin role to verified emails in NUXT_ACL_ADMINS, in the authorization:roles hook. Everyone else holds the roles assigned in the admin. See Authentication. |
server/db/migrations/sqlite/ | The committed SQL, snapshot and journal for the database. |
modules/libsql-binding.ts | A local module that puts the SQLite driver's native binding in the server build. |
authorization-roles.ts is a server plugin: a file that Nitro, Nuxt's server engine, runs at
start-up.
Add your own pages under app/pages, components under app/components and API routes under server/api. Nuxt
auto-imports components, composables and utils from app/. It also auto-imports server utils from server/utils.
What the modules give you
The app installs Users, Authorization, Account, Admin, Widget and Menu, and each installs the modules it depends on. The modules on the workspace starter page lists what each one gives you.
Next steps
- Configuration – see how
nuxt.config.tsand the environment variables tie these together. - Authentication – change how people sign in and who gets the
adminrole.