Platform administration
NuxtStart uses Better Auth's Admin plugin for application-wide user administration. The
stored Better Auth role remains admin; NuxtStart calls a user with that role a
Platform Admin.
Terminology
| Term | Meaning |
|---|---|
| Platform Admin | A user authorized to administer the whole NuxtStart application through Better Auth's Admin plugin. |
| Platform Administration | The application-owned management area currently served under /admin/**. |
| Organization Admin | A future, organization-scoped membership role provided by Better Auth's Organization plugin. |
| Platform Admin alert recipient | An email address configured to receive internal system alerts; it is not an authorization role. |
Use the scoped terms in application-owned names and UI. Keep upstream Better Auth names
unchanged when referring to its API or persisted values, including admin(),
adminClient(), authClient.admin, and user.role === 'admin'.
Future organization support
NuxtStart does not install Better Auth's Organization plugin. Consumers can add it later
and retain its built-in owner, admin, and member roles.
The two admin values do not conflict:
- The Admin plugin stores the Platform Admin role on
user.role. - The Organization plugin stores an Organization Admin role on a membership associated with one user and one organization.
- Platform authority does not automatically grant organization membership or organization permissions.
Keep platform authorization and organization authorization behind their corresponding
Better Auth APIs. Avoid a generic isAdmin helper because it hides which authority is
being checked.
Internal alert recipients
Configure internal system-alert recipients with a comma-separated runtime variable:
NUXT_EMAIL_PLATFORM_ADMIN_EMAILS=operator@example.com,backup@example.com
Recipient configuration is independent of authentication. Adding an address does not grant the Platform Admin role, and granting the role does not subscribe an address.
The value is read when a request is served, not while the application builds. The email
layer declares runtimeConfig.email.platformAdminEmails and leaves it empty, so Nitro
fills it from the deployment's own environment under the name above. Supply it the way
your platform supplies any other secret — a Cloudflare secret, a Railway variable, a
Docker environment file. Nothing has to be present on the build machine.
The name is therefore not free. Nitro derives it from the config path, so a different variable name is not read at all, and delivery becomes a silent no-op rather than an error.
This replaces the earlier build variable PLATFORM_ADMIN_EMAILS, which was supplied as a
module option. Because module options resolve while nuxt.config.ts is evaluated, the
addresses were written into the server bundle as plain text and travelled inside every
deployment artifact and build cache that held a copy. Rename the variable in each
deployment environment before deploying code that expects it.
Development credentials
The starter's development forms retain these local-only defaults:
Email: admin@mail.com
Password: adminadmin
These values identify a convenient development login; they do not grant a role by themselves.