Middleware & SDK Setup

The last step in the installation process is configuring Server Middleware and SDK in your frontend application. You will need them to communicate with Builder's Content API and fetch dynamic data which fuels your frontend components.

Before following along, make sure you've read either of the bootstrapping guides: for Nuxt or Next.

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

Middleware setup

In this part of the guide, you are going to install some dependencies.

Key concept: Server Middleware

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

If you haven't set up Server Middleware yet, please follow this guide on how to create one

To setup Builder integration with Middleware, navigate to the /apps/storefront-middleware directory:

cd apps/storefront-middleware

Next, install the @vsf-enterprise/builder-api package. It augments the Server Middleware with Builder-specific endpoints required by the integration:

npm install @vsf-enterprise/builder-api

With this library in place, in your middleware.config.js register Builder integration in your Server Middleware. Replace <builder_apikey> with your environment's credentials:

// middleware.config.js

module.exports = {
  integrations: {
    builder: {
      location: '@vsf-enterprise/builder-api/server',
      configuration: {
        apiKey: '<builder_apikey>',
      },
    },
  },
};

Other CMS already installed?

Be aware that you may have already installed any other CMS integration, like Contentful. In that case you just need to switch the configuration with the Builder one.

Security

You can pass your API Key (<builder_apikey>) here in the configuration. This is the server context so your sensitive data is safe. You can use environment variable as well.

Read the Builder docs to find out where to get your API Key.

SDK setup

Now, let's install the Alokai Builder SDK module into your frontend application. It extends the SDK core with methods responsible for communication with the Server Middleware and - in turn - with Builder's Content Delivery API.

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

Navigate to your frontend application directory:

cd apps/storefront-unified-nextjs

Run this command.

npm install @vsf-enterprise/builder-sdk

With this library in place, to your sdk.config.ts file if you don't already have one. Use it to initialize the SDK and configure the Builder module. apiUrl should point to the address of your Server Middleware you spun up at the end of the previous section.

import { builderModule } from '@vsf-enterprise/builder-sdk';
import type { Endpoints as BuilderEndpoints } from "@vsf-enterprise/builder-api";

export const { getSdk } = createSdk(options, ({ buildModule, middlewareUrl, ... }) => ({
  // ... other SDKs configuration
  builder: buildModule(builderModule<BuilderEndpoints>, {
    apiUrl: `${middlewareUrl}/builder`,
  }),
}));

Now your SDK is ready to use. 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 Builder. Luckily, Alokai ships with a pre-defined set of Content Types matching your frontend components. Proceed to the Bootstrapping builder guide to find out how you can import them into your space.