CLI: what and why

The CLI is the central entry point for developing code in your project. So, its primary function is to synchronize files for development.

This article explains exactly what the CLI does for this function and why it's done that way.

There are 2 reasons you wouldn't want to use the staging instance of your API hub as the backend-for-frontend:

You're also working on extensions
You're working on code that requires newer code than what's deployed in staging (for example, from a certain Git branch)

For all other cases, we recommend that you work against the staging instance and don't use file synchronization.

If you're in 1 of the 2 mentioned scenarios, you'll need a sandbox where the development instance of the API hub will run. See the sandboxes article for the steps to set that up and start developing.

When you run frontastic run, this starts the Next.js frontend process by running yarn dev, the build process of the extensions and the file synchronization of the build artifacts to the sandbox so that they run there. It also sets up a hostname <project>-<customer>.frontastic.io.local to access the studio of the sandbox.

Build process

The CLI will start the build process of the extensions, which is watching for changes and rebuilds the bundle automatically. That bundle is then synchronized to the sandbox, where the new version is automatically loaded. You can see the build's status in the backend build log page, which is shown by pressing b on the CLI dashboard.

The CLI starts yarn run extensions:watch to build the extensions. If you want to customize the build process, you can change what happens for this command in the package.json. But, ensure that the resulting build artifact is placed at backend/build/bundle.min.js. Otherwise, it won't be synced to the sandbox.

Up(s) and down(s)

There are many challenges involved when synchronizing code with a remote server, like synchronization performance and conflict detection. commercetools Frontend uses Mutagen to solve these. We only synchronize files up, so you shouldn't find any conflicts.

If you have any issues, see the filesync troubleshooting article.

Custom filesync config

If you need to modify how files are synchronized between your local machine and a sandbox, you can provide your own Mutagen configuration instead of the one generated by CLI.

You can find the Mutagen configuration file format in the Mutagen documentation.

Instead of writing your own configuration file from scratch, you can modify the configuration file generated by the CLI. To access the file, you'll need to run the CLI with the activated file synchronization once, and then you'll find the generated configuration at .frontastic/mutagen.yml. Copy this file, for example, to custom-mutagen.yml, and make the changes you want.

To use the modified configuration, start the CLI with the --mutagenConfig flag, passing the path to the configuration file, for example:

frontastic run --mutagenConfig ./custom-mutagen.yml

Instead of --mutagenConfig, you can also use the shorthand flag -m.

The CLI regenerates the .frontastic/mutagen.yml if you change the configuration of the CLI. This won't be done with your custom configuration. You'll have to modify it yourself, for example, if you change the hostname of your sandbox.