Compatibility and releases

Nuxt Customer Portal is an MIT-licensed monorepo. Copyright belongs to “Nuxt Customer Portal contributors”; the repository root LICENSE governs the reusable packages and source unless a file says otherwise.

Public package versions and changelogs are managed with Changesets. Starting with 0.3.0, releases use ordinary version numbers without an alpha suffix. Before 1.0.0, minor releases may introduce documented breaking changes; patch releases preserve compatibility. Review each package's changelog before upgrading and keep all official packages on the same version.

Adoption and release status

All 16 official packages are published on npm at 0.4.3. The installation guide uses this version of the portal kit to create a standalone application.

Timesheets and invoicing are used by the maintainers' software agency. Version 0.3.0 is the first npm release. Use 0.3.1 or newer when creating a portal on Node 24; it fixes template copying during setup. Evaluate compatibility with your host, deployment, and custom modules before upgrading. Service Requests is an optional example extension for developers.

Supported baseline

• Nuxt 4 and compatible Vue/framework peers;
• PostgreSQL;
• English and Dutch;
• npm, pnpm, Yarn, and Bun consumers.

Documented package exports are the compatibility surface. Host aliases, physical paths across packages, demo shell components, raw internal records, and direct changes to official database tables are not.

Upgrading

1. Read package Changesets and compare manifests.
2. Run nuxt-customer-portal doctor.
3. Inspect nuxt-customer-portal db status and the pending SQL.
4. Test a fresh database and an upgrade copy.
5. Run typecheck, builds, package tests, and critical portal workflows.
6. Deploy with a restorable backup and a forward-repair plan.

Checksums make published migration files immutable. Disabling a package leaves its data intact. A host that alters an official table must fork or explicitly take over that provider's migration stream and cannot assume upstream compatibility.

Publishing

Publishing a GitHub release runs the package tests and tarball verification before publishing every unpublished public package version to npm. npm authentication uses trusted publishing and GitHub's short-lived OIDC identity; the release workflow does not require a long-lived npm token.

The first publication of a new package requires an authenticated npm account with permission to publish to the @nuxt-customer-portal scope. npm requires the package to exist before a trusted publisher can be configured. After the initial publication, configure release-npm-packages.yml as the trusted GitHub Actions publisher for each package, with owner ludulicious and repository nuxt-customer-portal. See the npm trusted-publisher prerequisites. A release does not change DNS, migrate production databases, or modify Ludulicious.

Maintainers should follow the documentation release checklist: prepare docs first, verify locally packed packages, publish npm packages, verify a clean registry installation, and then deploy the matching documentation.