Frontastic coding guide

When working with Frontastic, you can, in general, follow your own coding guidelines. However, some rules are needed for your code to function properly with Frontastic, 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 with Frontastic.

Git workflow

Frontastic 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 Frontastic studioFrontastic studio - The interface you use to manage, build, and edit all areas of your project and commerce sites. Previously known as `backstage`..

Where to put your code

Within your GitHub customer repositoryGitHub customer repository - Where your code lives in GitHub for all your projects, you can have many project folders within your customer repository., you'll find the below codebase structure:

  • paas folder
  • packages/<project>
  • <customer>/automation folder
  • <customer>_<project> folder(s)
  • files needed for your project

A Frontastic project is structured into multiple JavaScript packages. So you only need to work in packages/<project>. All other folders shouldn't be touched.

Underpackages/<project> there's:

  • frontend/ for the Next.js code of your frontend
  • backend/ for the backend extensions code
  • types/ should contain shared types that define the contract between frontend and backend

You can execute the frontastic install in the repository root to have all dependencies installed with one single command.

🚧

Avoid using yarn install because you'll have to mannually run it in all projects and folders. Instead, use frontastic install as it will take care of all installations.

These 3 directories contain your own code. There are small exceptions of files generated by Frontastic (clearly mentioned at the top of the file) and some configuration files (for example, package.json and yarn.lock) that require special handling. But besides these, you're basically free to do whatever you want in these directories.

All your project code should reside in the packages/<project> directory.

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 your Frontastic code structure for easy sharing between different Frontastic projects for you. To find out how to do this, see the sharing code between projects article.

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.

Frontastic component namespace
Inside your schema files, thetasticType field is used for the identifier of your Frontastic componentFrontastic component - A customizable building block that's used together with other components to create a commerce site. Known as `tastic` for short in code.. To avoid namespace conflicts, we recommend naming your Frontastic componentsFrontastic components - A customizable building block that's used together with other components to create a commerce site. Known as `tastic` for short in code. 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
Frontastic component type: frontastic/ui/product/list

Folder Structure
All of your Frontastic components live underneath the frontastic/tastics folder. We recommend adding a folder for each Frontastic componentFrontastic component - A customizable building block that's used together with other components to create a commerce site. Known as `tastic` for short in code.. For example:

  • frontastic/tastics/product/details/schema.json
  • frontastic/tastics/product/details/index.tsx

Useful tips

Frontastic suggests 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 unpushed 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.

Frontastic 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 preconnect usage with Google Fonts
next/link-passhref - Enforce passHref prop usage with custom Link components
next/no-css-tags - Prevent manual stylesheet 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 are 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.


Did this page help you?