Frontastic CLI: What and why

The Frontastic CLI 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 CLI 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 CLI 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 CLI 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 CLI starts the correct webpack processes for you. If you're interested, you can find the start scripts that the Frontastic CLI runs automatically in the package.json file of your project.

Once the Frontastic CLI 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 studio), the data and basic HTML structure need to be available which is provided by the Frontastic API hub, our backend-for-frontend. To prevent every developer from having to run their own instance of this service, the Frontastic CLI 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 hub server while the frontend code is handled locally. This way you retain the full power of Frontastic studio and API hub 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 CLI 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 CLI 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 hub 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 sandbox where the development instance of the Frontastic API hub 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 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. 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.