Bootstrapping Alokai Storefront

This documentation explains how to get started with the builder integration in Alokai Storefront.

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 Alokai Storefront, developers can seamlessly incorporate dynamic CMS components into their applications, enhancing both content delivery and user experience.

Requirements

Builder environment,
Node.js version 18.x,
@vsf-enterprise NPM registry access.

Something's missing?

If you don't have an Alokai Storefront project yet, request a demo from our Sales team. If you don't have a Builder space yet, we suggest you get in touch with Builder.io team and request a demo.

Creating `.npmrc` file

If you haven't already configured your project to access our enterprise-level packages, it's essential to create and configure a .npmrc file. Please add this file to the root directory of your repository with the following content:

@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 with Alokai Storefront, navigate to the /apps/storefront-unified-[framework] directory:

cd apps/storefront-unified-nextjs

In most cases as the Alokai project is a monorepo, you will need to run the command from the /apps/storefront-unified-[framework] directory.

Here's a brief overview of the directory structure:

    /vsf-application
    ├─ apps/
    │  └─ storefront-middleware/           # VSF Middleware application
    │  ├─ storefront-unified-[framework]/  # Your framework of choose application
    ├─ packages/                           # Shared code or components
    ├─ turbo.json                          # Turborepo configuration
    └─ package.json                        # Project dependencies (monorepo entrypoint)

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 use the CLI, simply run the following command from the root of your frontend project:

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
    ├── app
    |   └── globals.css
    ├── builder
    |   └── components.ts    
    |   └── builder.tsx     
    ├── components
    │   └── cms
    │       ├── layout
    │       │   ├── Footer.tsx
    │       │   └── MegaMenu.tsx
    │       └── page
    │           ├── ... CMS Components
    │       └── wrappers
    │           ├── RenderComponent.tsx
    └── pages
        ├── [...page].tsx
        └── layout.tsx

Next.js Context

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

Running the CLI will add the /schemas directory to your project. It will be required for Bootstrapping Builder. If you already have a Builder space filled with Alokai content types, you can skip this step and delete the /schemas directory altogether.

Installing dependencies

The UI layer of the integration relies on Storefront UI and its dependencies. This will be preinstalled in your Alokai Storefront Application. Now, install the required packages for the Builder integration. Run the following command from the root of your frontend project:

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

What next?

Your frontend application now has the necessary scaffolding to showcase dynamic CMS components. To complete the setup, it requires a mechanism for retrieving data from Builder. Continue by exploring the Middleware and SDK Setup guide to learn about its installation process.