Quick start

Prerequisites

Contentstack access & knowledge
Install Node.js version 16.0

Using the integration

In this section, we will explain in a step-by-step guide how to use Contentstack integration in your front-end application.

Middleware preparation

Key concept - Middleware

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

Already have the server middleware configured?

If you have the server middleware configured, you can move directly to the SDK preparation part.

Install the API Client to communicate with Contentstack. This package is used to create a server-to-server connection with the Contentstack backend and the server middleware.

yarn add @vsf-enterprise/contentstack-api

Install @vue-storefront/middleware package. This package is used to create the server middleware.

yarn add @vue-storefront/middleware@rc

Create a file middleware.config.js with server middleware configuration.

// middleware.config.js

require('dotenv').config();

module.exports = {
  integrations: {
    cnts: {
      location: '@vsf-enterprise/contentstack-api/server',
      configuration: {
        key: 'CONTENT_DELIVERY_KEY',
        token: 'CONTENT_DELIVERY_TOKEN',
        env: 'CONTENT_ENV',
      }
    }
  }
};

Create a middleware.js file. This script is used to run the server middleware.

// middleware.js

const { createServer } = require('@vue-storefront/middleware');
const { integrations } = require('./middleware.config');
const cors = require('cors');

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

Your middleware is ready. You can start it by running node middleware.js

SDK preparation

Key concept - SDK

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

Install the SDK package. It's the core of the SDK.

yarn add @vsf-enterprise/sdk

Install the Contentstack module. It extends the SDK core with methods to communicate with Contentstack.

yarn add @vsf-enterprise/contentstack-sdk

Initialize the SDK. Configure Contentstack module with apiUrl that points to the server middleware.

import { contentstackModule } from '@vsf-enterprise/contentstack-sdk';
import type { Endpoints as ContentstackEndpoints } from "@vsf-enterprise/contentstack-api";

export const { getSdk } = createSdk(options, ({ buildModule, config, getRequestHeaders }) => ({
  // ...
  contentful: buildModule(contentstackModule<ContentstackEndpoints>, {
    apiUrl: `${config.middlewareUrl}/cnts`,
  }),
}));

Your SDK is ready and you can call methods with sdk.contentstack.<METHOD_NAME>. To see a full list of methods offered by the Contentstack module, check out the API Reference.