Frontastic CLI: What and why

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

This article explains exactly what the Frontastic 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 Frontastic 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 Frontastic sandbox where the development instance of the Frontastic API hub will run. See the Frontastic 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> to access the studio of the sandbox.

Build process

The Frontastic 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 Frontastic CLI dashboard.

The Frontastic 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 Frontastic sandbox.

Up(s) and down(s)

There are many challenges involved when synchronizing code with a remote server, like synchronization performance and conflict detection. Frontastic 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 Frontastic sandbox, you can provide your own Mutagen configuration instead of the one generated by Frontastic 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 Frontastic CLI. To access the file, you'll need to run the Frontastic 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 Frontastic 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 Frontastic CLI regenerates the .frontastic/mutagen.yml if you change the configuration of the Frontastic 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.

Did this page help you?