Documentation

Coding guide

Elevate, May 20-22-2025, Miami Beach, Florida

When working with commercetools Frontend, you can, in general, follow your own coding guidelines. However, some rules are needed for your code to function properly, which we'll go through in this article. On top of that, we recommend some additional guidelines which will help you streamline your development workflow.

Git workflow

Our CI automatically builds pushes to the master branch. Those builds will be tested, and, if successful, compiled assets will be available for deployment.
This doesn't mean that you can't use branches. However, branches will only be tested when pushed to the remote origin, and no assets will be compiled (see the deployment article for more information).
Any successful master build will automatically be deployed to staging (if you didn't explicitly request this to be turned off) and be available for rollout to production through the Studio.

Sharing code

You can use any standard means of the JavaScript community (like publishing npm packages or similar) to share code between different projects. However, we prepared the code structure for easy sharing between different projects for you.

Best practices

React
Use default exports for React Components and named exports for everything else.
Schema files
Although you can name your schema files any name you want, we recommend sticking with schema.json.
Frontend component namespace
Inside your schema files, thetasticType field is used for the identifier of your Frontend component. To avoid namespace conflicts, we recommend naming your Frontend components using the following way: <project>/<theme>/<tastic-name>
You can further categorize like: <project>/<theme>/<products>/<tastic-name>
To avoid confusion, it's a good idea to match the folder structure with the tasticType. For example: Folder: tastics/product/list Component type: frontastic/ui/product/list
Folder Structure
All of your components live underneath the frontastic/tastics folder. We recommend adding a folder for each Frontend component. For example:
  • frontastic/tastics/product/details/schema.json
  • frontastic/tastics/product/details/index.tsx

Useful tips

We suggest a ‘master-based development flow’ (originally known as ‘trunk-based development’). This means branches are generally discouraged. All code should go directly into master. This requires each push (ideally each commit) to leave the codebase fully functional. Feature flagging and branch-by-abstraction are programming techniques to make this possible. With that, your team will benefit from a faster, more agile development workflow.

We also suggest following these rules for a smooth setup:

  • Pull before you push
  • Rebase un-pushed changes in favor of merge (set pull.rebase globally to true)
  • Structure your work in logical steps and commit parts of your work together which deal with a common purpose
  • Frequent, smaller commits are preferred over large batches of work
  • Push frequently, but always ensure a working state in master

Linting

ESLint statically analyzes your code to quickly find problems. Many problems ESLint finds can be automatically fixed. ESLint fixes are syntax-aware so that you won't experience errors introduced by traditional find-and-replace algorithms.

commercetools Frontend uses ESLint rules that improve your site's Core Web Vitals.

The following rules, which are also the recommended rules by Next.js, are enabled by default:

next/google-font-display - Enforce optional or swap font-display behavior with Google Fonts
next/google-font-preconnect - Enforce pre-connect usage with Google Fonts
next/link-passhref - Enforce passHref prop usage with custom Link components
next/no-css-tags - Prevent manual style sheet tags
next/no-document-import-in-page - Disallow importing next/document outside of pages/document.js
next/no-head-import-in-document - Disallow importing next/head in pages/document.js
next/no-html-link-for-pages - Prohibit HTML anchor links to pages without a Link component
next/no-img-element - Prohibit usage of HTML <img> element
next/no-page-custom-font - Prevent page-only custom fonts
next/no-sync-scripts - Forbid synchronous scripts
next/no-title-in-document-head - Disallow using <title> with Head from next/document
next/no-unwanted-polyfillio - Prevent duplicate polyfills from Polyfill.io
next/inline-script-id - Enforce id attribute on next/script components with inline content
next/no-typos - Ensure no typos were made declaring Next.js's data fetching function
next/next-script-for-ga - use the script component to defer loading of the script until necessary
We also include the following rules to get reasonable defaults: eslint:recommendedplugin:react/recommended see eslint-plugin-react plugin:react-hooks/recommended see eslint-plugin-react-hooks
In your project root folder, you'll find the settings in the .eslintrc.JSON file. You can add your own rules or adapt the existing rules in that file.

Use the below command to run ESLint:

yarn lint

We recommend adding linting directly to your code editor or development environment to get immediate feedback.

Linting in vim
There're a variety of extensions that can add linting support to vim and Neovim. If you're using vim, we recommend either ALE or CoC. If you're using Neovim, you can use the integrated Language Server Protocol to run eslint_d in the background. Here's a handy guide on how to do that.
Linting in Visual Studio Code
To integrate ESLint into Visual Studio Code, you'll need to install the ESLint extension for Visual Studio Code. Search for ESLint in the Extensions tab and click Install once you have located the extension. Once ESLint is installed in Visual Studio Code, you'll notice colorful underlining in your jsx/tsx files highlighting errors. These markers are color-coded based on severity. If you hover over your underlined code, you'll see a message that explains the error to you.

Prettier/code formatting

We also recommend setting up your editor to use Prettier to format a document when it's saved.

Prettier in vim
If you're using vim, you can install Prettier using this installation guide. Or, if you're using Neovim, you can install Prettier using this installation guide.
Prettier in Visual Studio Code
To integrate Prettier into Visual Studio Code, you'll need to install the Prettier extension for Visual Studio Code. You can find it in the marketplace and click Install.