Step-by-Step Guide

Overview

The SCAYLE Storefront Application and it's Storefront SDK packages are ready for Nuxt 4. You can now make the switch without changing your setup or rewriting your whole code.

Moving to Nuxt 4 is a simple step forward. It uses the same architectural foundation as Nuxt 3, so you wont need to change your business logic or redo large portions of your projects implementation. The update mainly cleansup the file & directory structure, as well as improving TypeScript handling behind the scenes.

As every project is different, you might need to handle a few small adjustments in your configuration, custom modules or custom implementation. This guide shows you how to upgrade your Storefront Application to Nuxt 4.

Summary

• No business logic or runtime behavior changes are introduced.
• The Storefront SDK works unchanged on Nuxt 4.
• The Storefront Application adopts Nuxt 4 directory conventions.
• Transitional compatibility flags are removed.
• Types move to shared/types and imports standardize to #shared/*.
• Local modules remove Nuxt Bridge metadata.
• The locale module order may require adjustment in some setups.
• @nuxt/image version 2 is recommended for peer dependency alignment.

Further Reading

• Announcing Nuxt 4.0 - High-level summary of the release and its goals
• Nuxt 4 Upgrade Guide - Practical guide to migrating from Nuxt 3 to Nuxt 4

Notable Changes

The Storefront SDK and the Storefront Application behave the same under Nuxt 4. There is no Nuxt 4 specific SDK package and no functional changes compared to Nuxt 3. The upgrade removes the compatibility mode and transitional flags and only changes structure and metadata.

Key characteristics of the Nuxt 4 upgrade:

• Structural alignment with Nuxt 4 directory conventions.
• Cleanup of transitional compatibility flags and metadata.
• Tooling stabilization for long term maintenance.

Limitations

The upgrade is low risk, but it is not fully zero effort. Some areas may still require manual work.

• Custom Nuxt modules may require metadata cleanup.
• Some third party development tooling such as Storybook may lag behind Nuxt 4 compatibility.
• Module initialization order is now more deterministic and may surface hidden race conditions.

Supported Versions and Packages

All supported SDK packages run unchanged on Nuxt versions greater than or equal to >=3.13.0 and greater than or equal to >=4.2.0.

The following packages are compatible with Nuxt 4:

• @scayle/[email protected]
• @scayle/[email protected]
• @scayle/[email protected]
• @scayle/[email protected]
• @scayle/[email protected]
• @scayle/[email protected]
• @scayle/[email protected]
• @scayle/[email protected]
• @scayle/[email protected]
• @scayle/[email protected]
• @scayle/[email protected]

1. Before You Start

Complete the following steps before upgrading application code:

1. Update Node.js to version 22 or version 24.
2. Upgrade Nuxt to the latest Nuxt 3 (v3.20.2) point release before moving to Nuxt 4.
3. Update all SCAYLE Storefront SDK packages to the latest compatible versions.
4. Audit third party Nuxt modules for Nuxt 4 compatibility.
5. Remove transitional Nuxt 3 compatibility flags.
6. Clean up unused modules and legacy imports.
7. Review the Nuxt 4 compatible Storefront Application reference.
8. Familiarize yourself with Nuxt 4 directory conventions.
9. Identify all custom local Nuxt modules.
10. Identify all Storybook and locale related configuration.
11. List all imports from ~/types, ~~/shared, and similar aliases.

2. Implementation Guide

2.1 Dependencies

Framework Upgrade

1. Upgrade Nuxt to version 4.2.0 or higher.
2. Verify compatibility with all Storefront SDK packages.
3. Confirm that no Storefront SDK upgrades are required purely for Nuxt 4 support.

Peer Dependency Update for @scayle/nuxt-image-provider

The peer dependency for @scayle/nuxt-image-provider now expects @nuxt/image version 2. Updating is not required to keep your storefront running, but it is recommended to avoid warnings and stay aligned with Nuxt 4.

1. Update the project dependency.

bash

Copy

No code changes are required in the application or in Storefront SDK usage.

2.2 Development Tooling

Storybook

The currently used Storybook Nuxt module introduces stability issues with the Nuxt 4 development server. This does not affect production builds, but it impacts local development and CI environments that rely on Storybook builds.

1. Update the Storybook Nuxt module to the latest available version.
2. Validate development server startup and HMR.
3. Temporarily disable Storybook if it blocks local development.

Validate all build time tooling such as PostCSS, ESLint, and Prettier under Nuxt 4.

2.3 Configuration

nuxt.config.ts

Nuxt 4 runs natively without requiring a compatibility mode. Remove the transitional compatibility configuration.

1. Remove the compatibility configuration from nuxt.config.ts.

ts

Copy

No replacement configuration is required.

The Storefront SDK does not require configuration changes when upgrading from Nuxt 3 to Nuxt 4. All existing configuration options behave identically under Nuxt 4. No options were added, removed, renamed, or restructured as part of Nuxt 4 compatibility.

Dedupe configuration

We added dedupe to avoid multiple Nuxt instances.
It forces Vite to always use the root versions of core Nuxt packages and prevents subtle bugs caused by duplicated runtimes when using linked packages, monorepos, or nested dependencies.

typescript

Copy

We still rely on a small part of Nuxt’s experimental configuration to preserve the current runtime behavior during the upgrade. This keeps file watching stable and disables the new cached data behavior that the Storefront SDK does not yet support. These settings avoid subtle runtime changes while moving to Nuxt 4 and can be revisited once the SDK fully supports the new defaults.

typescript

Copy

3. Technical Architecture

3.1 Nuxt 4 Path Structure

Nuxt 4 formalizes the separation between runtime contexts by introducing a stricter and more explicit directory layout. This structure defines how Nuxt resolves code across the application, server, and shared layers.

See: New Directory Structure

The following directories become canonical in Nuxt 4:

• app/ contains client side application code such as pages, layouts, components, and composables.
• server/ contains server only logic such as API routes, middleware, and Nitro handlers.
• shared/ contains cross context resources that are imported by both the app and server runtimes.
• layers/ contains reusable Nuxt layers when the project uses layered architecture.

3.2 Project Structure Changes

Type Definitions

All TypeScript type definitions used by the application now follow Nuxt 4’s recommended directory layout.

See Point 4: TypeScript Configuration Splitting

1. Move shared types from ./types/ to ./shared/types/.
2. Keep app scoped types in ./app/types/.

Before:

Copy

After:

Copy

Import Path Updates

All imports referencing moved types must use standardized Nuxt 4 aliases.

1. Update imports across components, composables, utilities, and pages.
2. Replace ~/types/* and ~~/shared/* imports with Nuxt 4 aliases.

Before:

ts

Copy

After:

ts

Copy

All alias based imports using ~~/shared/ are replaced with #shared/. This change ensures consistency with Nuxt 4’s standardized alias resolution.

Local Module Changes

All local Nuxt modules remove the deprecated bridge option from their ModuleOptions type.

1. Remove the bridge option from module compatibility metadata.
2. Ensure modules explicitly target Nuxt 3 and Nuxt 4 only.

Before:

ts

Copy

After:

ts

Copy

Why this changed:

• Nuxt Bridge is not supported in Nuxt 4.
• The bridge flag is now invalid and would misrepresent module compatibility.
• All local modules now explicitly target Nuxt 3 and Nuxt 4 without transitional behavior.

3.3 Module Load Order Changes

Locale Module

The initialization order of the locale module changes under Nuxt 4. Nuxt 4 resolves and initializes modules more deterministically, which can surface implicit ordering assumptions.

See: Corrected Module Loading Order in Layers

Impact:

• Modules that depend on locale data during initialization may encounter race conditions.
• Symptoms typically include inconsistent runtime configuration during startup.

Required action if issues occur:

1. Reorder affected modules explicitly in nuxt.config.ts so the locale module initializes before dependent modules.

ts

Copy

No changes are required if no race conditions are observed.

3.4 Storefront SDK Behavior

The Storefront SDKs do not change their runtime behavior under Nuxt 4. All APIs behave exactly as they do under Nuxt 3. There are no changes to data fetching, rendering, or module initialization semantics.

3.5 TypeScript Behavior

There are no runtime behavior changes in TypeScript execution. Type resolution relies on the new shared and app directory layout. All existing types remain unchanged in shape and semantics.

What This Means for Storefronts

Existing Storefronts

If you already run Nuxt 3.13 or later and use the latest SDK versions:

• You can upgrade to Nuxt 4 without changing Storefront SDK configuration or application code.
• Update @nuxt/image to version 2 to stay within the supported peer dependency range.

Existing Storefront Applications

If you upgrade an existing Nuxt 3 Storefront Application:

1. Move all shared types from ./types/ to ./shared/types/.
2. Update all imports to use #shared/types/* or #app/types/*.
3. Remove future.compatibilityVersion from nuxt.config.ts.
4. Update local Nuxt modules to remove the bridge option.

New Storefronts and Storefront Applications on Nuxt 4

If you start a new storefront or Storefront Application on Nuxt 4:

• Use the same Storefront SDK setup as for Nuxt 3.
• Follow the existing Nuxt 3 Storefront documentation.
• Use the shared directory for cross context types and utilities.
• Use app for client side application structure.
• Do not include compatibility flags or Bridge metadata.
• Ensure that @nuxt/image version 2 is installed.

Troubleshooting