Workspace starter

What you'll have afterwards:

• A Nuxt 4 web app on http://localhost:3000 where people sign up, sign in and manage their account.
• You, signed in with the admin role, so the admin area at /admin is open to you.
• User management at /admin/users, where you list, create and edit users.

Use this starter for a website. It is a pnpm workspace with one host app in apps/web, built on the published @frigear-nu modules.

Prerequisites

The tools in Requirements. Nothing else.

1. Create the project

Copy .starters/workspace:

pnpm create frigear-app my-app --platform web
cd my-app
git init

pnpx giget@latest gh:Frigear-nu/frigear-nu/.starters/workspace my-app
cd my-app
git init && corepack enable && pnpm install
pnpm prepare:env

2. Run it

Put your own email in NUXT_ACL_ADMINS in apps/web/.env, then start the app:

pnpm dev

3. Sign in

Open http://localhost:3000, choose Create account and sign up with that email. Signing up sends a verification email (verifyEmail is on), printed in the terminal that runs pnpm dev: open its link and press Continue to sign in. NUXT_ACL_ADMINS only counts for a verified address.

Passkeys are on. On Security (/account/security), add one. From then on the passkey button on the sign-in page signs you in without a password, on any device your passkey syncs to.

Installation explains each of these steps, what you should see afterwards and what to do when the admin role does not apply.

What is in the starter

Project structure explains each file.

The modules

The app installs these modules directly. Each one installs the modules it depends on, such as Auth, Notify and UI.

Configuration shows the full apps/web/nuxt.config.ts and explains each option.

Who may do what

User management is a set of permissions (users:read, users:list, users:create, users:update, users:delete, users:manage) that Users registers. The starter's admin role holds them through grant: ['*'], and a user's roles are assigned on their page in the admin (roles:assign). Give another role some of them in authorization.roles:

export default defineNuxtConfig({
  authorization: {
    defaultRoles: ['user'],
    roles: {
      admin: { label: 'Admin', grant: ['*'] },
      support: { label: 'Support', grant: ['admin:access', 'users:read', 'users:list', 'users:update'], inherit: ['user'] },
      user: { label: 'User' },
    },
  },
})

Staff can only change a user who holds no permission they lack, so support cannot edit an admin. A rule of your own, such as "only admins may give someone a staff address", is a policy in server/policies.ts. The Frigear website app has a fuller example with a chain of roles.

Other ways to grow it

• Add a module. Add a module walks through adding Forms, with its encryption key, permissions and migration. To find the right module, see Which module do I need?.
• Use an existing Nuxt 4 app instead.Use an existing Nuxt 4 app lists the packages and files to copy.
• Go to production. Deployment lists the database, secrets and email driver to set. Launch on your final https domain: a passkey belongs to the domain it was created on, so moving means users add theirs again. Set authentication.settings.webAuthn: false to offer email and password only.

Next steps

• Add a mobile app – let a phone app sign in at this app.
• Modules – browse what else you can add.
• UX patterns – follow the shared patterns when you add screens.
• Writing a module – build a module of your own.