Vue Storefront is now Alokai! Learn More
Setup for Nuxt

Setup for Nuxt

By default, Alokai integration with Amplience is meant to be used with our Alokai Storefront solution. However, if you want to use it with a pure Nuxt 3 application, this guide explains how to get started.

Requirements

Something's missing?

If you don't have a Nuxt 3 project yet, create one by following the official guide. If you don't have an Amplience space yet, we suggest you request a demo from the Amplience team.

Creating .npmrc file

In order to start working with our enterprise packages, add a .npmrc file with the following content to the root of your repository:

@vsf-enterprise:registry=https://registrynpm.storefrontcloud.io

Importing integration components

Alokai ships with a CLI tool for CMS integrations which will import all of the frontend acceleration files into your project.

The CLI tool has been tested with a fresh Nuxt 3 project.

To use the CLI, simply run the following command from the root of your project:

npx @vsf-enterprise/cms-cli amplience:components -f nuxt

This will create (or overwrite) the following files in your project:

├── components
│   └── cms
│       ├── layout
│       │   ├── Footer.vue
│       │   └── MegaMenu.vue
│       ├── page
│       │   ├── Accordion.vue
│       │   ├── Banner.vue
│       │   ├── Card.vue
│       │   ├── CategoryCard.vue
│       │   ├── Editorial.vue
│       │   ├── Gallery.vue
│       │   ├── Grid.vue
│       │   ├── Hero.vue
│       │   ├── NewsletterBox.vue
│       │   ├── ProductCard.vue
│       │   └── Scrollable.vue
│       └── wrappers
│           └── RenderComponent.vue
├── layouts
│   └── amplience.vue
└── pages
    ├── [...slug].vue
    └── amplience-visualization.tsx

Enabling layouts

The amplience.vue layout will only take effect when the NuxtLayout component is used within the app.vue component. Make sure yours has it.

<template>
  <NuxtLayout />
</template>

Installing dependencies

The integration requires a few additional dependencies to run. That includes supplementary packages related to Storefront UI or agnostic CMS components.

Check out our compatibility matrix for the integration before installing the dependencies described in this guide.

npm

npm install @vsf-enterprise/cms-components-utils @vue-storefront/sdk @vue-storefront/middleware @vsf-enterprise/amplience-sdk @vsf-enterprise/amplience-api dc-visualization-sdk @nuxtjs/google-fonts @nuxt/image && npm install --save-dev typescript @vue-storefront/nuxt @storefront-ui/typography

yarn

yarn add @vsf-enterprise/cms-components-utils @storefront-ui/typography @vue-storefront/sdk @vue-storefront/middleware @vsf-enterprise/amplience-sdk @vsf-enterprise/amplience-api dc-visualization-sdk @nuxtjs/google-fonts @nuxt/image && yarn add -D typescript @vue-storefront/nuxt

Loading Storefront UI

The UI layer of the integration relies on Storefront UI and its dependencies. Follow the official guide to install the library in your project.

Loading Google Fonts

The default Storefront UI setup uses Google Fonts. In the Installing dependencies section, you've already installed the @nuxtjs/google-fonts module in your project. Now, register it in your nuxt.config.ts:

export default defineNuxtConfig({
  // ...
  modules: [
    // ...
    ['@nuxtjs/google-fonts', {
      families: {
        'Red Hat Display': [400, 500, 700],
        'Red Hat Text': [300, 400, 500, 700]
      }
    }]
  ]
});

To complete the fonts setup, add the Storefront UI typography plugin to your Tailwind config file:

import sfTypography from '@storefront-ui/typography';

export default {
  // ...
  plugins: [sfTypography],
};

Loading Nuxt Image

In the Installing dependencies section, you've already installed the @nuxt/image module in your project. Now, register it in your nuxt.config.ts:

export default defineNuxtConfig({
  // ...
  modules: [
    // ...
    '@nuxt/image'
  ]
});

Configuring Server Middleware

The next step is configuring Amplience integration in the Server Middleware.

Key concept: Server Middleware

Middleware concept is described in detail in our Key concepts: Server Middleware docs.

In the root of your project, create a middleware.config.js file to register Amplience integration in your Server Middleware. Replace <amplience_hubname> and <amplience_staging_env> with your environment's credentials:

export default {
  integrations: {
    ampl: {
      location: '@vsf-enterprise/amplience-api/server',
      configuration: {
        hubName: '<amplience_hubname>',
        stagingEnvironment: '<amplience_staging_env>',
      },
    },
  },
};

Good to know

Read the Amplience docs to find out where to get your hubName and stagingEnvironment.

With the configuration file in place, we need a script which will import it and spin up the Server Middleware on a dedicated port. Let's create it in the root of the project and name it middleware.js:

import { createServer } from '@vue-storefront/middleware';
import config from './middleware.config.js';
import cors from 'cors';

const { integrations } = config;

(async () => {
  const app = await createServer({ integrations });
  // By default it's running on the localhost.
  const host = process.argv[2] ?? '0.0.0.0';
  // By default it's running on the port 8181.
  const port = process.argv[3] ?? 8181;
  const CORS_MIDDLEWARE_NAME = 'corsMiddleware';

  const corsMiddleware = app._router.stack.find(
    (middleware) => middleware.name === CORS_MIDDLEWARE_NAME
  );

  // You can overwrite the cors settings by defining allowed origins.
  corsMiddleware.handle = cors({
    origin: ['http://localhost:3000'],
    credentials: true,
  });

  app.listen(port, host, () => {
    console.log(`Middleware started: ${host}:${port}`);
  });
})();

Now your Server Middleware should be ready for take off. You can start it by running node middleware.js.

Configuring Alokai SDK

The last step in the installation process is configuring Alokai SDK for Amplience in your frontend application. It ships with functions responsible for fetching and resolving raw data from Amplience.

Key concept - SDK

SDK is described in detail in our Key concepts: SDK docs. Also, read about middlewareModule used by our Amplience SDK module under the hood.

In the root of your project, create a new sdk.config.ts file with the following content:

import { amplienceModule } from '@vsf-enterprise/amplience-sdk';
import type { Endpoints as AmplienceEndpoints } from "@vsf-enterprise/amplience-api";

export default defineSdkConfig(
  ({ buildModule }) => ({
    amplience: buildModule(amplienceModule<AmplienceEndpoints>, {
      apiUrl: 'http://localhost:8181/ampl',
    }),
  }),
);

Next, register the @vue-storefront/nuxt module in your nuxt.config.ts. It will expose a global useSdk function which is used by some of the Amplience integration components (e.g. amplience.vue).

export default defineNuxtConfig({
  // ...
  modules: [
    // ...
    '@vue-storefront/nuxt',
  ]
});

Finally, set the verbatimModuleSyntax to false in your tsconfig.json file. We need it so that we don't get errors from integration components that don't use the import type.

{
  // ...
  "compilerOptions": {
    // ...
    "verbatimModuleSyntax": false
  }
}

Now your Amplience SDK is ready for take off. To see a full list of available methods, check out the API Reference.

What next?

With your frontend application ready, it's time to prepare a corresponding setup in Amplience. Fortunately, Alokai ships with a pre-defined set of Content Types matching your frontend components. Proceed to the Bootstrapping Amplience guide to find out how you can import them into your space.