Installation
Requirements
- a current Node.js LTS release;
- Nuxt 4;
- PostgreSQL;
- pnpm, npm, Yarn, or Bun.
Install the preset
The preset contains core, the neutral UI fallback, authentication, organizations, and administration. Add optional business packages explicitly.
pnpm add @nuxt-customer-portal/preset @nuxt-customer-portal/kit
pnpm add @nuxt-customer-portal/service-requests @nuxt-customer-portal/timesheets
npm install @nuxt-customer-portal/preset @nuxt-customer-portal/kit
npm install @nuxt-customer-portal/service-requests @nuxt-customer-portal/timesheets
yarn add @nuxt-customer-portal/preset @nuxt-customer-portal/kit
yarn add @nuxt-customer-portal/service-requests @nuxt-customer-portal/timesheets
bun add @nuxt-customer-portal/preset @nuxt-customer-portal/kit
bun add @nuxt-customer-portal/service-requests @nuxt-customer-portal/timesheets
The packages are currently versioned together as 0.1.0-alpha.0. The first repository milestone pack-tests these packages but does not publish them; use monorepo tarballs until the public prerelease is announced.
Compose the layers
import { definePortalConfig } from '@nuxt-customer-portal/kit'
export default definePortalConfig({
layers: [
'@nuxt-customer-portal/preset',
'@nuxt-customer-portal/service-requests',
'@nuxt-customer-portal/timesheets'
]
})
import portal from './portal.config'
export default defineNuxtConfig({
extends: portal.nuxtLayers
})
Configure the environment
Generate and retain a unique Better Auth secret:
openssl rand -base64 32
Set at least:
DATABASE_URL=postgresql://postgres:postgres@localhost:5432/customer_portal
PUBLIC_URL=http://localhost:3000
BETTER_AUTH_URL=http://localhost:3000
BETTER_AUTH_SECRET=<paste-the-generated-secret>
PORTAL_REGISTRATION_MODE=open
Validate and migrate
npx nuxt-customer-portal doctor
npx nuxt-customer-portal db status
npx nuxt-customer-portal db migrate
doctor detects duplicate providers, missing dependencies, and dependency cycles before SQL runs. Migrations execute in dependency order under a PostgreSQL advisory lock. Review package and local-layer migrations before applying them to an existing database.
Start Nuxt with your package manager's normal development command. Next, review usage, shell customization, or database migrations.