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 with linked versions. The installation guide uses the latest release of the portal kit to create a standalone application, so its commands do not need to change for each release.

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.

Release 0.12.1

Version 0.12.1 fixes invoice line editor type checking in clean generated portal installations and repairs the Node 22.19 Yarn consumer verification dependency graph. Release infrastructure and package-version changes now run full verification before merging, with downloadable demo browser diagnostics on failure. Keep all 16 official packages aligned on 0.12.1; no new migrations are required. The 0.12.0 tag is retained unchanged. The features described below are included, but registry and Docker availability still depend on successful full release verification and publication.

Release 0.12.0

Version 0.12.0 adds trusted connected website configuration in General settings for credentialed account session checks and sign-out. External access remains opt-in and restricted to explicitly allowed origins. Custom hosts can configure PORTAL_AUTH_WEBSITE_ORIGINS; review the origin allowlist before enabling website access.

Draft invoices support adding, editing, removing, and drag/keyboard reordering of lines, with only the selected line open for editing. Adding a line focuses its description. VAT is explicitly a percentage, and new draft lines use the workspace default without changing existing rates. New invoice navigation works directly, disabled sources do not produce misleading warnings, and the source-selection step is skipped when only free-form invoicing is available. Duplicated invoices and credit notes open in draft edit mode.

The default appearance restores native Nuxt UI styling. Primary colors drive actions, selection, and focus states while ordinary surfaces and text remain neutral. Explicit appearance overrides and Brutal remain supported; custom surfaces are mode-specific and live preview defaults stay isolated from saved overrides. The primary color controls are aligned, and the logo fallback sublabel is removed.

Client slugs are suggested from display names and remain editable. Existing names can change without silently changing saved URLs. Detail pages use /clients/<slug>, and old ID links redirect to the current slug. Slug edits preserve list return state; earlier slugs are not retained as aliases. Internal IDs and permissions are unchanged.

Keep all 16 official packages aligned on 0.12.0. No new database migrations are required when upgrading from 0.11.0; older installations must apply all outstanding migrations. Review external origin allowlists, custom appearance overrides, client links, and invoice editing before deployment. Creating the GitHub release starts full verification; npm and Docker publication remain blocked until every verification job succeeds. The release record alone does not confirm registry or image availability.

Release 0.11.0

Version 0.11.0 adds Duplicate invoice and Credit invoice actions that create new drafts without sending emails. Full credit notes reference the original invoice and reverse its rounded amounts and exact tax, with protection against multiple active credits. Administrators can permanently delete unissued drafts after confirmation, releasing linked timesheets for invoicing again.

Draft recipient details can be previewed and refreshed from current client data, including selecting the billing contact. Issued invoice snapshots remain unchanged, and organization, draft status, and contact ownership are validated on save. Invoice details and PDFs prefer the portal's light-mode full logo, with provider-organization fallback and PNG, JPEG, and WebP support in PDFs.

Email-provider settings display actionable encryption configuration errors. Server failures use secret-safe structured diagnostics, including migration and constraint metadata, without logging credentials or query values. Keep the existing encryption key when one is already configured; do not replace it as a troubleshooting step.

Keep all 16 official packages aligned on 0.11.0. No new database migrations are required when upgrading from 0.10.3; older installations must apply all outstanding migrations. Review draft invoice deletion, duplication, full credit notes, recipient refresh, invoice branding, and email-provider configuration before deployment. Creating a GitHub release starts full verification; npm and Docker publication remain blocked until every verification job succeeds.

Release 0.10.3

Version 0.10.3 refines product administration and store booking. Product paths link to the store, and previews retain a Back to product link through booking and checkout. Ended and cancelled offers can be archived and restored without reactivating them; archived offers are available through a link when present.

Booking automatically selects the sole available team member and hides the redundant selector. Timezone controls sit beside the calendar navigation and stay in the same position during time selection. Calendar hover feedback, selected-date emphasis, control spacing, and timezone label visibility are improved. Shared links use clearer hover and active states without underlines. Booking and checkout summaries, including mobile offering details, now render sanitized Markdown using the configured product theme.

Keep all 16 official packages aligned on 0.10.3. When upgrading from 0.10.2, apply Products migration 0027_offer_archive.sql through the normal migration command before deploying. This adds offer archival state without changing existing offer status. Older installations must also apply any outstanding migrations, including Planning migration 0006_availability_segments.sql when upgrading from 0.10.0. Review product preview return navigation, archived offers, and booking timezone controls after upgrading.

Release 0.10.2

Version 0.10.2 allows bookings and rescheduling while Zoom authorization is missing or expired, using the existing pending-link and later-notification flow. Google Calendar authorization and live booking-time conflict checks remain required. Availability generation is faster for large calendars, independent provider checks run concurrently, and the slot picker reuses recently visited months without caching booking-time conflict checks.

Email Provider and Email Template are now tabs under Portal Settings. Email Texts has its own administration page, with redirects from existing email administration URLs. Legal-page and email-text language selectors only offer enabled portal languages and are hidden for single-language portals. The duplicate Email Texts heading is removed.

Shared Nuxt UI and Tailwind overrides align card, input, Markdown editor, dialog, and menu surfaces in light and dark modes while preserving native input padding, sizing, rounded corners, and theme branding. Products forms use simpler nested sections, and main-menu and submenu hover states use the same brand tint as Clients.

Keep all 16 official packages aligned on 0.10.2. No new database migrations are required when upgrading from 0.10.1; upgrades from 0.10.0 must still apply Planning migration 0006_availability_segments.sql as described below. Existing email settings and localized content are preserved. Review enabled portal languages, email settings navigation, and any custom Nuxt UI or surface overrides after upgrading. Bookings made without healthy Zoom authorization still require that connection to be restored before a meeting link can be created and sent.

Release 0.10.1

Version 0.10.1 improves appointment planning with Google Calendar availability mirrors that split around confirmed appointments and grace time, explicit recurring-availability deletion choices, and confirmation before staff appointment changes. Successful changes immediately refresh the open appointment drawer.

Availability and timesheets now include calendar week pickers. External events show concise Busy/Free status in tooltips, and Busy all-day events subtly shade blocked day columns without treating Free events as conflicts. Sales invoice lists retain filters, sorting, pagination and scroll position when returning from details. Image adjustment immediately shows the uncropped editing source and crop selection without requiring a zoom change.

Localized terms and privacy policies support sanitized Markdown, with legal-page links in expanded and collapsed sidebars.

Keep all 16 official packages aligned on 0.10.1. When upgrading from 0.10.0, apply Planning migration 0006_availability_segments.sql through the normal migration command before deploying. This adds segment-aware synchronization for availability mirrors; existing recurring availability is preserved. Review Google Calendar availability and localized legal content after upgrading.

Release 0.10.0

Version 0.10.0 adds separate desktop and mobile authentication backgrounds, with upload, preview, removal, and single-image fallback controls. Existing branding settings remain compatible. Authentication forms align near the top on mobile while retaining desktop positioning.

The portal home route now redirects to /dashboard, preserving authentication, onboarding, and saved homepage content. Logout goes directly to /login. Sign-in pages have clearer English/Dutch welcome and required-field messages without the home back button. Account menus use Account Settings, redundant main-navigation links are removed, and account settings use the standard portal background. Personal client avatars show the account owner's profile image when available.

Store owners receive paid or accepted order notifications, and assigned appointment hosts receive booking, update, and cancellation notifications. Internal messages have customizable English/Dutch templates and retry-safe delivery receipts. Calendar synchronization no longer sends provider notices; calendar-conflict alerts and customer appointment notifications remain active.

Keep all 16 official packages aligned on 0.10.0. No new database migrations are required when upgrading from 0.9.1. Review custom home-route and logout integrations and internal notification templates before deploying.

Release 0.9.1

Version 0.9.1 includes the media library, product image selection and unified sidebar described below. Version 0.9.0 failed full release verification before npm or Docker publication. Use 0.9.1 for these changes. This release avoids generated API route type-inference limits when loading timesheet navigation capabilities and switching demo users, keeps the invoice sender form compatible with current Vue template checks, and corrects a consumer verification override that forced newer Nuxt modules onto an incompatible older Kit version. Keep all official packages aligned on 0.9.1 and apply Products migrations 0024_media_library.sql, 0025_media_variants.sql, and 0026_product_media.sql when upgrading from 0.8.9.

Release 0.9.0

Version 0.9.0 adds an authenticated store media library with Studio-style image editing, batch review, retained originals, configurable image variants and independent crops. New product images use searchable shared media, with drag and keyboard ordering, protected delivery, and deletion checks for images in use. Existing product images and purchased-file uploads are preserved. Variant preset changes apply when an image is next saved.

The opt-in unified sidebar includes nested module navigation, keyboard-accessible collapsed flyouts, module pages in global search and footer collapse controls. SaaS Portal enables this layout.

Keep all official packages on 0.9.0 and apply Products migrations 0024_media_library.sql, 0025_media_variants.sql, and 0026_product_media.sql before deploying the matching portal image. Review custom sidebar integrations when enabling unified navigation.

Release 0.8.9

Version 0.8.9 shows booked appointment dates, time ranges, and customer timezones on thank-you and order details pages, including current rescheduled times and cancellation status. Store texts previews can include a sample appointment with an adjustable UTC date/time and display timezone. Google and GitHub login buttons now follow the running server’s opt-in settings and credentials, including in prebuilt images. All official packages and the portal Docker image use 0.8.9; no new database migrations are required when upgrading from 0.8.8.

Release 0.8.8

Version 0.8.8 includes the portal branding and admin order details improvements described below and avoids generated API route type-inference limits in consumer applications. Version 0.8.7 failed full release verification before npm or Docker publication. Use 0.8.8 for these changes. All official packages and the portal Docker image use 0.8.8; no new database migrations are required when upgrading from 0.8.6.

Release 0.8.7

Version 0.8.7 makes checkout, order and thank-you pages inherit the portal logo unless a checkout-specific logo is defined. Purchase-page logos and return links align left, and store settings have more space below their tabs. Admin order cards now open a regular portal page with customer, linked client, payment and invoice details, plus a Client order details card showing the customer-facing content without its logo. Shareable public client links remain available. All official packages and the portal Docker image use 0.8.7; no new database migrations are required when upgrading from 0.8.6.

Release 0.8.6

Version 0.8.6 fixes the starter wizard rejecting valid selections containing invoice integrations, including Products and Planning. Saved setup metadata is accepted when setup resumes. Use 0.8.6 when creating a new portal. All official packages and the portal Docker image use 0.8.6; no new database migrations are required when upgrading from 0.8.5.

Release 0.8.5

Version 0.8.5 makes manual fulfillment an opt-in product setting, preserves order-list filters and scroll position when visiting order details or invoices, reduces invoice email status lookups, and shares the branded receipt layout across purchase pages. Test orders are clearly identified using their saved purchase mode. Products and historical orders without the new fulfillment setting do not require manual tracking; later product edits do not change existing order snapshots. No new database migrations are required when upgrading from 0.8.4.

Release 0.8.4

Version 0.8.4 adds account-free order links, purchased external links and media previews, and Store texts for shared page wording and product-specific purchase introductions. Apply Products migrations 0022_page_texts.sql and 0023_product_page_texts.sql before deploying. Existing thank-you customizations and purchase snapshots are preserved. All official npm packages and the portal Docker image use version 0.8.4.

Release 0.8.0

Version 0.8.0 adds deferred invoicing with immediate fulfillment, unlisted products with unguessable slugs, protected purchase-file links, conditional email text, and a shared release verification gate. Apply Products migrations 0019_purchase_downloads.sql and 0020_deferred_payments.sql, and Invoices migration 0004_deferred_invoice_review.sql, before deploying. Existing stores retain online payments and listed products. Deferred checkout requires tax-inclusive prices and the invoice integration; review each draft's taxes before sending.

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

Pull requests run lightweight checks: source unit tests, formatting/lint, the SaaS boundary check, and the primary portal type check. Documentation content tests run only for relevant changes. Full source builds, demo browser tests, and SaaS portal Docker publication run before release instead of on every PR or merge. Npm publication, package tarball/consumer compatibility checks, and installer/starter verification jobs are paused. Documentation browser tests and the standalone docs Docker build are separate manual checks, not gates for the SaaS portal image.

Publishing a GitHub release starts Release portal image (release-saas-portal.yml). It resolves the release tag to an exact commit and runs Full release verification once against the source code. Only the SaaS portal Docker image is published; npm publication is disabled. Docker-only release tags may advance without changing public package versions or consuming pending Changesets. Docker publication waits for all verification jobs to pass and publishes from the verified commit. A failed, cancelled, or skipped check prevents publication. The portal image's SHA tag, revision label, and deployment reference identify that commit, including manual release retries.

To run source verification without publishing, manually start Full release verification and provide a branch, tag, or commit. To retry Docker publication, manually start Release portal image (release-saas-portal.yml) from the updated default branch with the existing stable release_tag (for example v1.2.3). The Docker publisher has no separate release or manual publication trigger. Historical tagged workflows and reruns retain their original configuration, including retired package/installer checks and npm publication on older releases; use the updated default-branch workflow for Docker-only retries. Existing release tags are not moved.

Package-distribution and installer source remain in the repository, but are not part of the active release process. Do not run pnpm release-packages or re-enable npm publishing without an explicit decision to resume package releases. A GitHub or Docker release does not imply npm package availability. A release does not change DNS, migrate production databases, or modify Ludulicious.

Maintainers should follow the documentation release checklist: prepare docs first, verify the published SaaS portal Docker image, and then deploy matching documentation. Existing npm installation guides describe previously published packages and must not be advanced to unpublished versions.