Migrate Existing Storefronts

The following page provides a guide on how to use your Storefront Hosting solution for the first time in case you already have an existing Storefront Application codebase. Depending on which version your Storefront Application is, certain configuration changes might be required.

Step by Step Guide

1. Update `@scayle/storefront-nuxt` Version

Storefront Hosting requires Storefront Nuxt version 8.25.0 or higher. You will need to upgrade your @scayle/storefront-nuxt dependency to at least 8.25.0. For a detailed list of the required changes to perform this upgrade smoothly, please refer to the Storefront SDKs Changelogs and the Upgrade Guides.

2. Install KV Store Drivers

Storefront Hosting includes a built-in KV (Key-Value) store, primarily intended for caching. To integrate with this SCAYLE KV store, you need to install the following drivers:

@scayle/unstorage-compression-driver: ^1.0.0
@scayle/unstorage-scayle-kv-driver: ^1.0.2

3. Configure Storage Mounts with Nitro Plugins

With @scayle/[email protected], the preferred way of defining storage mounts has changed. This update introduces the ability for your host application to define its own storage mounts, significantly enhancing the flexibility of managing cache and session storage options within your Nuxt project. To utilize @scayle/unstorage-scayle-kv-driver for caching, you'll need to create a new Nitro server plugin within your ./server/plugins directory that defines storage mounts required by the Storefront Application.

Here’s an example of how to configure these mounts, demonstrating the use of scayleKvDriver (wrapped with compressionDriver) for session and cache storage:

After defining the storage mounts within the Nitro plugin, the storage configuration within nuxt.config.ts can be removed.

For more details on the configuration, you can refer to our documentation on Storage.

4. Use Cloudflare for SSR Caching

Storefront Hosting leverages Cloudflare's global cache to ensure that requests are served quickly and efficiently. By utilizing Cloudflare, we can disable the SSR cache at the application level, which reduces the overall load on the application and improves user experience as the cache is closer to the user.

To achieve this, the route rule for cacheable routes needs to be updated to only attach the cache-control header to the request. This can be configured in your nuxt.config.ts file as follows:

5. Use Environment Variables

When building a Storefront Application with Storefront Hosting, environment variables are not available at build time. Values read from process.env must therefore be replaced with a static value or have a valid fallback.

For example: const SHOP_SELECTOR_MODE = 'path' or const SHOP_SELECTOR_MODE = process.env.SHOP_SELECTOR_MODE ?? 'path';

Once you have completed these migration steps and your repository is successfully connected to Storefront Hosting, you are ready to deploy your application. For detailed instructions on the deployment process, please refer to our Deployment Documentation.