Installation

Create your own working copy of the configurable SaaS portal with one setup command. It includes client access, Timesheets, Invoices, Products, Planning, their invoice integrations, and browser setup for branding, modules, store configuration, homepage content, and legal pages.

Requirements

• Node.js 22.19 or newer on a Nuxt-compatible LTS release;
• npm, pnpm, Yarn, or Bun;
• Docker with Compose for a local database, or a connection URL for an empty PostgreSQL database.

The command below installs the published 0.4.3 release. The kit generates a project with matching versions of the portal packages, including @nuxt-customer-portal/saas-configuration. See compatibility and releases.

1. Create your portal

Run this from the parent directory where you want your new project:

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

Or use your preferred package manager:

pnpm dlx @nuxt-customer-portal/kit@0.4.3 init my-portal

yarn dlx @nuxt-customer-portal/kit@0.4.3 init my-portal

bunx @nuxt-customer-portal/kit@0.4.3 init my-portal

The wizard asks for your organization name, administrator name and email, package manager, and database choice. It then:

1. Creates a standalone Nuxt project in a new or empty directory.
2. Generates a private .env with unique authentication and email-encryption secrets.
3. Installs the portal packages and the configurable application's host files.
4. Starts PostgreSQL with Docker if selected, or connects to your empty database.
5. Asks you to choose and confirm an administrator password, applies migrations, and creates your verified administrator account.

The administrator password is masked and is not saved in the project files. The portal starts with invitation-only registration. Service Requests is available as an example extension and is off by default.

Connect to your own PostgreSQL database

If you choose Connect to an empty PostgreSQL database, enter a connection URL in this format:

postgresql://username:password@host:5432/database

Replace username and password with your database credentials, host with the database server address, 5432 with its port, and database with the name of your empty database. For example, a local database named my_portal, with user portal and password my-password, would use:

postgresql://portal:my-password@localhost:5432/my_portal

Your database provider may supply the full URL. Keep any connection options it includes, such as ?sslmode=require. Special characters in the username or password must be percent-encoded: for example, @ becomes %40 and # becomes %23. Leave existing encoded values unchanged.

Setup saves the connection URL as DATABASE_URL in the generated project's .env file. You can edit that file before running npm run setup again.

2. Start the portal

cd my-portal
npm run dev

Use pnpm run dev, yarn run dev, or bun run dev if you chose that manager. Open the login URL printed by the setup command, normally http://localhost:3000/login. If a local port is occupied, setup selects another available port and keeps the app and authentication URLs aligned.

Sign in with the administrator account you just created. A new account created by setup is already email-verified, so the first login works before you configure email delivery.

3. Make it yours

Complete the existing browser onboarding: branding and appearance, enabled modules, homepage content, and legal pages. Then follow your first portal workflow to add a client, record time, and create an invoice.

Configure email delivery before inviting team members or clients, verifying newly registered accounts, or sending invoice emails.

What is in your project?

Your project contains the configurable application's app/, public assets, translations, configuration, and a health route. Shared business features remain versioned package dependencies. The kit and portal.config.ts manage migrations and module composition.

You own these host files and can customize them or add a module. You do not need a copy of the monorepo to run the generated project.

Setup metadata is in portal.setup.json. Secrets are in the ignored .env, with an empty .env.example for reference. Keep your secrets private and review deployment before exposing the portal publicly.

Retry or install later

If installation or database setup fails, the generated files remain available. Correct the reported problem, then run these from your project directory, using the manager you selected:

npm install
npm run setup
npm run dev

Setup only initializes an empty database or resumes the database claimed by that generated project. It refuses another installation and never resets an existing administrator's password. To change a connection, edit DATABASE_URL in .env; the destination must still be empty or belong to this project.

To generate files without installing dependencies or touching a database, add --no-install to the init command. The wizard prints the remaining commands. With the Docker option, npm run db:stop stops the database while preserving its volume; npm run db:start starts it again.

Add the portal to an existing Nuxt application

Use Manual installation when you want to compose the packages into an existing host or build a minimal host yourself.

Run the wizard from the source checkout

From the repository root, after installing dependencies:

pnpm --filter @nuxt-customer-portal/kit build:template
node packages/kit/bin/nuxt-customer-portal.mjs init ../my-portal --no-install

The source command generates the same project as the packaged CLI. When testing unpublished changes, maintainers must install locally packed packages in the generated application. See the release checklist.