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.
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
--mutagenConfig, you can also use the shorthand flag
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.