Documentation

Set up a custom Git repository

Set up a custom Git repository for your commercetools Frontend project.

Prerequisites

To set up a Git repository for your commercetools Frontend project, you need the following:

Set up a new project

To set up a Git repository for your commercetools Frontend project, follow these steps:

  1. Create a directory for your project using the terminal by running the following command:

    Create project directoryTerminal
    mkdir PROJECT_NAME

  2. Change the working directory to the new directory by running the following command:

    Move into project directoryTerminal
    cd PROJECT_NAME

  3. Initialize the Git repository by running the following command:

    Initialize Git repositoryTerminal
    git init

  4. Scaffold your commercetools Frontend project by running the following command:

    Scaffold your commercetools Frontend projectTerminal
    frontastic scaffold CUSTOMER_NAME PROJECT_NAME

  5. Add and commit your code by running the following commands:

    Create your first commitTerminal
    git add . && git commit -m "Initial commit"

  6. Create the remote repository using git remote.

You can now push, pull, and fetch to or from your remote repository.

Build your project

To deploy your project, you need to build the application into JavaScript bundles. You can do this locally or in a Continuous Integration (CI) environment.

Backend extensions

To build the backend extensions, follow these steps:

  1. Run yarn install in the packages/PROJECT_NAME/backend directory.
  2. Run yarn build in the packages/PROJECT_NAME/backend directory.

After the yarn build command has finished executing, the build artifacts bundle.min.js and bundle.min.js.map will be available at this path packages/PROJECT_NAME/backend/build/.

Frontend website

Netlify builds and deploys your frontend website separately from the backend extensions. For further information about Netlify deployments, see Deploy frontend.

Deploy your project

Deploy backend extensions

To deploy your backend extensions, you need the following information:

  • PROJECT_NAME - String - Required. The name of your commercetools Frontend project.
  • BRANCH - String - Required. The name of the Git branch to deploy.
  • REVISION - String - Required. The full commit hash of the current HEAD.
  • VERSION - String - Required. The current time represented in the format YYYY.MM.DD.HH.mm. This value must be unique and sortable.
  • NODE_JS_VERSION - String - Required. The Node.js version for the Extension runner.
  • BUILD_SUCCESSFUL - Boolean - Optional. Defaults to false. Set it to true if the build was successful. Otherwise, set it to false. Only successful builds are stored in the Studio.
  • BUILD_TIME - String - Required. The date and time of the build in the RFC3339 format. For example, 2023-11-21T08:14:31.830Z.
  • BUILD_DURATION - Integer - Required. A numeric value for the build duration in seconds.
  • BUILD_LOG - String - Optional. Defaults to an empty string. The CI execution logs.
  • BUNDLE_PATH - String - Required. The path to the bundle.min.js file.
  • BUNDLE_MAP_PATH - String - Required. The path to the bundle.min.js.map file.
  • SHOULD_DEPLOY - Boolean - Optional. Defaults to false. Set it to true to deploy the build to the staging environment, or set it to false if you only want to upload the build.
  • STUDIO_URL - String - Required. Your Studio URL, in the format CUSTOMER_ID.frontastic.io.
  • API_ID - String - Required. The Studio API key ID.
  • API_KEY - String - Required. The Studio API key.

You can deploy your commercetools Frontend project when uploading the build (by setting shouldDeploy to true) or manually using the Studio (by setting shouldDeploy to false).

Upload the build

To upload the build using the CLI, follow these steps:

  1. To protect the Studio API key from being exposed in the shell logs, set the API credentials as environment variables by running the following commands.

    Set environment variables in the shell for authenticationTerminal
    export FRONTASTIC_CLI_CLIENT_ID=<API_ID>
    export FRONTASTIC_CLI_CLIENT_SECRET=<API_KEY>

  2. Run the upload command from your project directory.

    Upload the build using the upload commandTerminal
    frontastic upload \
    --project PROJECT_NAME \
    --branch BRANCH \
    --revision REVISION \
    --versionNumber VERSION \
    --nodeJsVersion NODE_JS_VERSION \
    --buildSuccessful BUILD_SUCCESSFUL \
    --buildTime BUILD_TIME \
    --buildDuration BUILD_DURATION  \
    --buildLog BUILD_LOG \
    --deploy SHOULD_DEPLOY \
    --extensionBundleFilePath BUNDLE_PATH \
    --extensionBundleMapFilePath BUNDLE_MAP_PATH \
    --url STUDIO_URL \
    /

If you face issues when installing the CLI on your CI, you can use the CLI without installation.

Deploy frontend

To deploy your frontend, you must connect your Git repository to Netlify. To do so, follow these steps:

  1. Add your Git repository to your Netlify dashboard.

  2. Set the following values for the build settings.

    • Runtime:Next.js
    • Base directory: packages/PROJECT_NAME/frontend
    • Build command: yarn build
    • Publish directory: packages/PROJECT_NAME/frontend/.next

  3. Set the following values for the environment variables in your Netlify site settings:

    • NETLIFY_USE_YARN: true
    • NEXT_PUBLIC_CLOUDINARY_CLOUD_NAME: CLOUDINARY_CLOUD_NAME
    • NEXT_PUBLIC_FRONTASTIC_HOST: https://PROJECT_NAME-CUSTOMER_NAME.frontastic.io/frontastic

  4. Set up website branch deployment and auto publishing.