Bootstrapping Next

This guide provides step-by-step instructions for integrating Builder with a Next 13 application. Builder is a powerful dynamic content management system that allows developers to manage, deliver, and optimize content for various digital experiences. By integrating Builder with Next 13, developers can seamlessly incorporate dynamic CMS components into their applications, enhancing both content delivery and user experience.

The Builder integration is exclusive to our Enterprise offering.

Requirements

Next 13 project with next version 13.4.6 or higher,
Builder environment,
Node.js version 18.x,
@vsf-enterprise NPM registry access.

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 Builder space yet, we suggest you get in touch with Builder and request a demo.

Creating `.npmrc` file

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.

The CLI tool has been tested with a fresh Next 13 project without the App Router.

Be sure to run the command from the Next.js project.

In most cases as the Alokai project is a monorepo, you will need to run the command from the apps/web directory.

Here's a brief overview of the directory structure:

/vsf-application
├─ apps/
│  ├─ web/              # Next.js application
│  └─ server/           # VSF Middleware application
├─ packages/            # Shared code or components
├─ turbo.json           # Turborepo configuration
└─ package.json         # Project dependencies (monorepo entrypoint)

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

.

In a Turborepo (monorepo framework), the apps folder is a key directory where individual applications are stored. This structure helps in maintaining a clear separation of concerns and simplifies dependency management. For a project that includes both a Next.js application and a server application (acting as middleware or an API), each of these should reside within the apps folder as separate entities.

To scaffold the needed files, run the following command from the root of your Next application:

npx @vsf-enterprise/cms-cli@latest builder next

If you don't have .npmrc file you can always use npm_config_registry flag to specify registry URL.

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

├── schemas
│    └── [component]
|       └── component.json
|           schema.model.json
|       settings.json
|
└── src
    ├── app
    |   └── globals.css
    ├── builder
    |   └── components.ts    
    |   └── builder.tsx     
    ├── components
    │   └── cms
    │       ├── layout
    │       │   ├── Footer.tsx
    │       │   └── MegaMenu.tsx
    │       └── page
    │           ├── ... CMS Components
    └── pages
        ├── [...page].tsx
        └── layout.tsx

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

Installing dependencies

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

You will also need to install other integration dependencies such as supplementary packages related to Storefront UI or agnostic CMS components. Run the following command to install them in your project:

# npm
npm install @builder.io/sdk @builder.io/react @storefront-ui/typography @vsf-enterprise/cms-components-utils

# yarn
yarn add @builder.io/sdk @builder.io/react @storefront-ui/typography @vsf-enterprise/cms-components-utils

Loading fonts

The default Storefront UI setup uses Google Fonts. One way to load these fonts to your project is by importing them in the Next's globals.css file, which is provided with the above mentioned CLI command.

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

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

module.exports = {
  // ...
  plugins: [sfTypography],
  theme: {
    fontFamily: {
      sans: 'Red Hat Text, sans-serif',
    }
  }
};

What next?

Now your Next.js application has the scaffolding required to display dynamic CMS components. However, it also needs a way to fetch the data from Builder. Proceed to the Middleware and SDK setup guide and learn how to install them.