Documentation

Set up a custom Git repository

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

Before moving your project to a custom Git repository, you must contact Support.

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 the backend extensions, you must upload the backend build to the Studio using the CLI. To do so, 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>

    Replace the following:

    • API_ID - String - Required. The ID of the Studio API key.
    • API_KEY - String - Required. The Studio 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 \
    --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 \
    /

    Replace the following:

    • PROJECT_NAME - String - Required. The name of your commercetools Frontend project.

    • BRANCH - String - Required. The name of the Git branch used to build the uploaded files.

    • REVISION - String - Required. The long commit hash of the current HEAD used to build the uploaded files.

      Do not use the short commit hash as this will cause indexing issues in the Studio.

    • 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.

    You can deploy your commercetools Frontend project to the staging environment:

    • When uploading the build, by setting SHOULD_DEPLOY to true.
    • Manually from the Studio, by setting SHOULD_DEPLOY to false.

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 deactivate auto publishing by locking deploys.

    Do not keep auto publishing active as this will cause deployment issues in the Studio.