Frontastic CLI: What and why

The Frontastic CLIFrontastic CLI - Our Commandline Interface (CLI) that you can use for frontend development. is the central entry point for developing code in your Frontastic project. So, its main functions are:

  1. Run and orchestrate frontend development tools
  2. Synchronize files for backend development

This article explains exactly what the Frontastic CLIFrontastic CLI - Our Commandline Interface (CLI) that you can use for frontend development. does for these functions and why it's done that way.

1. Run and orchestrate frontend development

To develop in Frontastic you basically need 2 things:

  • Compile and watch your frontend assets
  • Render Frontastic pages on that basis

The Frontastic CLIFrontastic CLI - Our Commandline Interface (CLI) that you can use for frontend development. handles both of these for you through the command frontastic run. But before you run that command, make sure you've:

  • Run yarn install (especially if you've just cloned your GitHub repository or you've switched to a different branch)
  • Run frontastic init then configured it for purely local development and selected the staging server

See the Frontastic CLI article for the steps to set up the Frontastic CLIFrontastic CLI - Our Commandline Interface (CLI) that you can use for frontend development. for the first time.

Compile and watch

Our bundle management (also known as packaging frontend code, like, JavaScript and CSS) tool of choice is webpack. We use it to:

  • Perform development compiles
  • Perform Server Side Rendering compiles
  • Generate production assets for deployment

So, the Frontastic CLIFrontastic CLI - Our Commandline Interface (CLI) that you can use for frontend development. starts the correct webpack processes for you. If you're interested, you can find the start scripts that the Frontastic CLIFrontastic CLI - Our Commandline Interface (CLI) that you can use for frontend development. runs automatically in the package.json file of your project.

Once the Frontastic CLIFrontastic CLI - Our Commandline Interface (CLI) that you can use for frontend development. has started, you can see the log output of webpack and you'll be able to identify any issues in, for example, Server Side Rendering that your code produces.

Render pages

In order for Frontastic to see your code in action on a Frontastic page (which is configured 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`.), the data and basic HTML structure need to be available which is provided by the Frontastic API hubAPI hub - The API hub combines our code, your code, and APIs to create the backend of a commerce site. Any backend development or extensions are done here. Known as `Catwalk` in code., our backend-for-frontend. To prevent every developer from having to run their own instance of this service, the Frontastic CLIFrontastic CLI - Our Commandline Interface (CLI) that you can use for frontend development. proxies HTTP calls for you and allows you to use the staging environment of your project as the backend instance, while it only replaces the frontend code with the local development versions.

We achieve this by running an HTTP proxy on your local machine that responds on http://<project>-<customer>.frontastic.io.local (your development URL). The proxy makes sure that backend-calls are directed to the API hubAPI hub - The API hub combines our code, your code, and APIs to create the backend of a commerce site. Any backend development or extensions are done here. Known as `Catwalk` in code. server while the frontend code is handled locally. This way you retain the full power of Frontastic studioFrontastic studio - The interface you use to manage, build, and edit all areas of your project and commerce sites. Previously known as `backstage`. and API hubAPI hub - The API hub combines our code, your code, and APIs to create the backend of a commerce site. Any backend development or extensions are done here. Known as `Catwalk` in code. while you have entirely local frontend development with full control and performance.

This proxy and the management of development hostnames are the reasons for the Frontastic CLIFrontastic CLI - Our Commandline Interface (CLI) that you can use for frontend development. requiring your root password during frontastic run:

  • For your ultimate convenience, we're running the development server on the standard HTTP port (80) so that you can reach the development site using normal http:// and don't need to specify an additional port (for example, :8080). But since port 80 is in the reserved system port range (1-1000) we require superuser privileges to start the process.
  • We use system utilities (namely the /etc/hosts file) to have a proper local resolution of our development URLs. The Frontastic CLIFrontastic CLI - Our Commandline Interface (CLI) that you can use for frontend development. needs to access these to manage hostname resolution which also requires superuser privileges.

2. Synchronize files for backend development

There are 2 reasons you wouldn't want to use the staging instance of your API hubAPI hub - The API hub combines our code, your code, and APIs to create the backend of a commerce site. Any backend development or extensions are done here. Known as `Catwalk` in code. as the backend-for-frontend:

  • You're also working on backend code extensions
  • You're working on frontend code that requires newer backend 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 (as explained in the above section) and don't use file synchronization.

If you're in 1 of the 2 mentioned scenarios, you'll need a Frontastic sandboxFrontastic sandbox - A virtual machine hosted in the cloud that you can use for backend and some frontend development. They're provisioned from the developer area of the Frontastic studio. where the development instance of the Frontastic API hubAPI hub - The API hub combines our code, your code, and APIs to create the backend of a commerce site. Any backend development or extensions are done here. Known as `Catwalk` in code. will run. Once that's running, run frontastic init and select local frontend development and then synchronize backend code in addition. Once you've done that, use frontastic run to start with development.

This will start the webpack instances, the proxy server, and take care of hostname resolution, as in the previous scenario, but it'll also synchronize your backend files.

See the Bringing up a Frontastic sandbox article for the full steps to set up a Frontastic sandboxFrontastic sandbox - A virtual machine hosted in the cloud that you can use for backend and some frontend development. They're provisioned from the developer area of the Frontastic studio..

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. For the best possible experience, we follow some simple rules for synchronization to mitigate (but can't entirely resolve) these:

  • Rule 1: Synchronize everything up, overwrite the remote version and delete what doesn't exist there (exceptions are some generated files and those mentioned in rules 2 and 3)
  • Rule 2: Synchronize installed dependencies down (overwrite and delete!) to allow auto-completion of those in the local IDE (skip tests and docs of dependencies)
  • Rule 3: Try bi-directional sync of dependencies definition files, such as composer.json and composer.lock

While the first 2 rules shouldn't usually cause any conflicts, the 3rd rule can be a tough challenge.

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


Did this page help you?