Vue Storefront is now Alokai! Learn More
Setup for Next

Setup for Next

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 Next 13 application, this guide explains how to get started.

Tested with these CLI options

The procedures described in this guide have been tested on a fresh Next 13 project created with the following CLI options:

- Would you like to use TypeScript? … Yes
- Would you like to use ESLint? … Yes
- Would you like to use Tailwind CSS? … No
- Would you like to use `src/` directory? … No
- Would you like to use App Router? (recommended) … No
- Would you like to customize the default import alias (@/*)? … Yes
- What import alias would you like configured? … ~/*

We cannot guarantee they will work correctly with a Next 13 project created with different options.

Requirements

Something's missing?

If you don't have a Next 13 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.

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

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

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

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

Enabling dynamic pages

If there is an index.tsx file in your /pages directory - delete it. Otherwise - once you run your application - it will conflict with the [[slug]].tsx component responsible for rendering dynamic CMS pages.

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 && npm install --save-dev typescript @vue-storefront/next @storefront-ui/typography

yarn

yarn add @vsf-enterprise/cms-components-utils @vue-storefront/sdk @vue-storefront/middleware @vsf-enterprise/amplience-sdk @vsf-enterprise/amplience-api dc-visualization-sdk && yarn add -D typescript @vue-storefront/next @storefront-ui/typography

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. One way to load these fonts to your project is by importing them at the very top of the Next's globals.css file:

@import url('https://fonts.googleapis.com/css2?family=Red+Hat+Display:wght@400;500;700&display=swap');
@import url('https://fonts.googleapis.com/css2?family=Red+Hat+Text:wght@300;400;500;700&display=swap');

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

const sfTypography = require('@storefront-ui/typography');

module.exports = {
  // ...
  plugins: [sfTypography],
};

Adjusting the global.css file

We recommend deleting all default Next style rules present in the globals.css file or, at least, the ones responsible for setting a gray background on your Next pages:

body {
  background: linear-gradient(
      to bottom,
      transparent,
      rgb(var(--background-end-rgb))
    )
    rgb(var(--background-start-rgb)
  );
}

Also, we recommend changing the extension of the global file from css to scss. This is the format we use in our Alokai Storefront projects.

Configuring Next images

Add the following images configuration to your next.config.js file:

module.exports = {
  // ...
  images: {
    remotePatterns: [
      {
        hostname: '*',
        protocol: 'https',
      },
    ],
  }
}

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 directory. In the directory, create a new middleware.config.js file to register Amplience integration in your Server Middleware. Replace <amplience_hubname> and <amplience_staging_env> with your environment's credentials:

module.exports = {
  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. In the same directory, let's create a middleware.js file:

const { createServer } = require('@vue-storefront/middleware');
const config = require('./middleware.config.js');
const cors = require('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/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 directory. Then, create a new sdk.config.ts file with the following content:

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

export const { getSdk } = createSdk({ middleware: { apiUrl: '' } }, ({ buildModule }) => ({
  amplience: buildModule(amplienceModule<AmplienceEndpoints>, {
    apiUrl: 'http://127.0.0.1:8181/ampl',
  }),
}));

export type Sdk = ReturnType<typeof getSdk>;

Next, create a new SdkProvider.ts file with the following content:

import { createSdkContext } from '@vue-storefront/next/client';
import { getSdk } from './sdk.config';

export const [SdkProvider, useSdk] = createSdkContext(getSdk());

Finally, create an index.ts barrell file exporting everything:

export * from './sdk.config';
export * from './SdkProvider';

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.