Vue Storefront is now Alokai! Learn More
Setup for Next

Setup for Next

By default, Alokai integration with Bloomreach Content 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 a Bloomreach Content environment yet, we suggest you get in touch with Bloomreach and request a demo.

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 files

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 bloomreach-content: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
  │           ├── BRXComponent.tsx
  │           └── RenderComponent.tsx
  ├── layouts
  │   └── BloomreachLayout.tsx
  └── pages
      └── [[...slug]].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 uses dependencies such as SDKs provided by Bloomreach, axios and supplementary packages related to Storefront UI, our Bloomreach Content SDK or agnostic CMS components. Run the following command to install them in your project:

npm

npm install @bloomreach/spa-sdk @bloomreach/react-sdk axios @vsf-enterprise/cms-components-utils @vue-storefront/sdk @vsf-enterprise/bloomreach-content-sdk && npm install --save-dev typescript @storefront-ui/typography @vue-storefront/next

yarn

yarn add @bloomreach/spa-sdk @bloomreach/react-sdk axios @vsf-enterprise/cms-components-utils @vue-storefront/sdk @vsf-enterprise/bloomreach-content-sdk && yarn add -D typescript @storefront-ui/typography @vue-storefront/next

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],
};

Removing the default Next styles

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)
  );
}

Configuring Bloomreach Content

The next step is adding the bloomreachContent configuration to the runtimeConfig object of your next.config.js file. It should contain the name of your Bloomreach Content environment and the name of the channel you want to fetch the data from.

module.exports = {
  // ...
  publicRuntimeConfig: {
    bloomreachContent: {
      environmentName: 'vuestorefront',
      channel: 'en'
    }
  }
}

Good to know

Keeping those properties in the main framework configuration file can be considered a good practice but is not mandatory. Especially with the channel property - most likely you will want to bind it with your application's i18n setup so that it can be dynamically evaluated at runtime.

// [[...slug]].tsx

import getConfig from 'next/config';

export const getServerSideProps = async ({
  req: request,
  resolvedUrl: path,
+ locale: channel,
}: GetServerSidePropsContext) => {
  const { publicRuntimeConfig } = getConfig();
  const {
    environmentName,
-   channel
  } = publicRuntimeConfig.bloomreachContent;
};

Configuring Next images

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

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

Configuring Alokai SDK

The last step in the process is configuring Alokai SDK for Bloomreach Content in your front-end application. It will provide you with handy utility functions responsible for resolving raw data from Bloomreach.

Key concept - SDK

SDK core is described in detail in our SDK docs.

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

import { BloomreachContentModuleType, bloomreachContentModule } from '@vsf-enterprise/bloomreach-content-sdk';
import { createSdk } from '@vue-storefront/next';

export const { getSdk } = createSdk({ middleware: { apiUrl: '' } }, ({ buildModule }) => ({
  bloomreachContent: buildModule<BloomreachContentModuleType>(bloomreachContentModule),
}));

export type Sdk = ReturnType<typeof getSdk>;

Next, create a new SdkProvider.tsx 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 Bloomreach Content SDK is ready for take off. To see a full list of available methods, check out the API Reference.

What next?

With your frontend configured, the last thing to do is Bootstrapping your Bloomreach Content environment.