Quick start
Prerequisites
- Commercetools configured - if you don't have your Commercetools configured, see our Configuration guide.
- Install Node.js version 16.x.x
Using the integration
In this section, we will explain in a step-by-step guide how to use Commercetools integration in your front-end application.
Middleware preparation
Key concept - Middleware
Middleware concept is described in detail in our Key concepts: Middleware docs.
- Install the API Client to communicate with Commercetools. This package is used to create a server-to-server connection with the Commercetools backend and the server middleware.
yarn add @vsf-enterprise/commercetools-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();
const stringToArrayValue = (val, separator = ',') => {
return typeof val === 'string' ? val.split(separator) : [];
}
module.exports = {
integrations: {
ct: {
location: '@vsf-enterprise/commercetools-api/server',
configuration: {
api: {
uri: process.env.VSF_API_URI,
apiHost: process.env.VSF_API_HOST,
authHost: process.env.VSF_API_AUTH_HOST,
projectKey: process.env.VSF_PROJECT_KEY,
clientId: process.env.VSF_API_CLIENT_ID,
clientSecret: process.env.VSF_API_CLIENT_SECRET,
scopes: stringToArrayValue(process.env.VSF_API_SCOPES)
},
serverApi: {
clientId: process.env.VSF_SERVER_API_CLIENT_ID,
clientSecret: process.env.VSF_SERVER_API_CLIENT_SECRET,
scopes: stringToArrayValue(process.env.VSF_SERVER_API_SCOPES),
operations: stringToArrayValue(process.env.VSF_SERVER_API_OPERATIONS),
},
/* Below is just an example configuration for currencies and languages */
currency: 'USD',
country: 'US',
languageMap: {
en: ['en', 'de'],
de: ['de', 'en']
}
},
}
}
};
- Configure environment variables in your
.env
file.
# .env
# The name of your commercetools project
VSF_PROJECT_KEY=
# URL of the GraphQL API
VSF_API_URI=
# URL of the HTTP server
VSF_API_HOST=
# URL of the Auth server
VSF_API_AUTH_HOST=
# Unique ID specific to the API client.
VSF_API_CLIENT_ID=
# Unique secret string specific to the API client.
VSF_API_CLIENT_SECRET=
# Comma Separated List of user permissions. For the list of available scopes and their descriptions.
VSF_API_SCOPES=
# The serverApi object contains the information necessary to request data from the GraphQL API
# with elevated permissions that users should not have.
VSF_SERVER_API_CLIENT_ID=
VSF_SERVER_API_CLIENT_SECRET=
VSF_SERVER_API_SCOPES=
VSF_SERVER_API_OPERATIONS=
# List of allowed origins separated by coma.
# Example: MIDDLEWARE_ALLOWED_ORIGINS=http://localhost:3000,https://mydomain.io
MIDDLEWARE_ALLOWED_ORIGINS=
- 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.
- Install the SDK package. It's the core of the SDK.
yarn add @vue-storefront/sdk
- Install the Commercetools module. It extends the SDK core with methods to communicate with Commercetools.
yarn add @vsf-enterprise/commercetools-sdk
- Initialize the SDK. Configure Commercetools module with
apiUrl
that points to the server middleware.
import { initSDK, buildModule, middlewareModule } from '@vue-storefront/sdk';
import { Endpoints as CTEndpoints } from '@vsf-enterprise/commercetools-api';
const sdkConfig = {
ct:
buildModule(
middlewareModule<CTEndpoints>,
{
apiUrl: 'http://localhost:8181/ct',
ssrApiUrl: 'http://localhost:8181/ct'
}
)
};
export const sdk = initSDK(sdkConfig);
- Your SDK is ready and you can call methods with
sdk.ct.<METHOD_NAME>
. To see a full list of methods offered by the Commercetools module, check out the API Reference.