Coding guide

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.