@nuxt-customer-portal/kit

Nuxt Customer Portal kit

Configuration and migration tooling shared by official, third-party, and local portal layers. portal.config.ts is the single source for Nuxt extends and database provider ordering. Migration SQL is immutable after release and each provider receives its own journal table.

Create a portal

npx @nuxt-customer-portal/kit@0.3.3 init my-portal

The interactive wizard creates a standalone copy of the configurable SaaS portal, generates secrets, installs dependencies, starts local PostgreSQL with Docker (or uses an empty database), and creates a verified administrator. Choose the password in the masked prompt; it is never stored in generated files or passed as a shell argument. The wizard also lets you choose which business modules to install. It automatically adds required modules and integration layers: Planning adds Products, Products adds Invoices and its invoice bridge, and selecting Timesheets with Invoices adds their bridge. The generated dependency list, portal layers, client defaults, and initial onboarding settings contain only the resolved selection. Finish branding, module settings, homepage, and legal settings in the browser.

For your own PostgreSQL database, use a connection URL in the form postgresql://username:password@host:5432/database. Replace each part with your database details, or paste the URL from your database provider, including any connection options such as ?sslmode=require. Percent-encode special characters in credentials (@ becomes %40, for example). Setup saves the URL in .env.

Use --no-install to generate files only. Run the generated project's setup script to resume after fixing an installation or database problem. Setup refuses non-empty unrelated databases, preserves existing files, and never resets an existing account's password. The generated app uses invitation-only registration.

The wizard can optionally copy the homepage, privacy page, and terms page into the generated host under app/pages/. Leave that option off to keep every page package-provided. To customize one page later, run for example:

pnpm portal page copy login

Available page names are home, privacy, terms, and login. The command copies the selected source and adds any direct dependency it needs. It refuses the operation before changing files when the destination already exists. Local Nuxt pages override the package layer route, so there is no duplicate route. Copied pages are owned by the host: edit them normally, and review upstream package changes yourself because upgrades do not update local copies.

The npm tarball contains a template prepared from apps/saas-portal by prepack. When running init from a source checkout, first run pnpm --filter @nuxt-customer-portal/kit build:template. This keeps generated projects aligned with the maintained configurable application.

Generated projects include local Prettier and ESLint configuration. Run pnpm format to apply formatting and lint fixes, pnpm format:check to verify without changing files, and pnpm lint to check code with zero warnings allowed. Use the equivalent run commands for your chosen package manager. Generated outputs, local environment files, and package-manager lockfiles are excluded from formatting.

Manage an existing portal

Grant the global system-administrator role to an existing user with:

nuxt-customer-portal admin grant --email admin@example.com

This changes only the platform role on the user; it does not modify any organization membership or organization role.

db adopt-legacy is a dry run unless --apply is passed. It only recognizes the complete 22-entry pre-package migration history and refuses unknown or partially migrated databases.

Harvest migration

Use nuxt-customer-portal harvest export --output <file> with HARVEST_ACCESS_TOKEN and HARVEST_ACCOUNT_ID in the environment to save a complete administrator export. Preview with harvest import --input <file> --mapping <file> --provider <slug> --actor <email>; apply the reviewed input with --apply --backup-confirmed. The mapping JSON contains users (Harvest user ID to existing provider member email) and optional clients (Harvest client ID to existing client organization ID). Set createHistoricalUsers: true to preserve unmapped people as distinct disabled historical members without invitations. Credits, written-off invoices and original lifecycle events are retained; externally billed time stays excluded from new invoicing even without a source invoice link. Apply the Timesheets and Invoices history migrations before importing.

See the Harvest migration guide for prerequisites, reconciliation, supported history, and limitations.