Frontastic CLI

The Frontastic CLI is the central entry point for frontend development with Frontastic. It's possible to run webpack, which prepares all frontend code, directly on your local machine and everything else in the cloud.

This article will show you how to install the Frontastic CLI and basic usage.

If you're using Windows, please skip to this section

Getting started

To run JS development locally, you'll need nodemon installed. You can do this by running the command below:

npm install -g nodemon

You'll need to have Homebrew for macOS or Linux.

Then you can use Homebrew to install the Frontastic CLI by running the below command:

brew tap frontasticgmbh/tap && brew install frontastic-cli

We update the Frontastic CLI regularly, to update to the latest version, run brew upgrade frontastic-cli.

You can also use Homebrew to install Yarn if you don't have Yarn already installed on your computer. To do this, run brew install yarn.

Then you can start in the basic usage section.

Getting started on Windows

To get the Frontastic CLI running on your Windows system, you'll need to download the latest package from the Frontastic CLI release page. Once downloaded you'll need to extract the zip folder and move the frontastic.exe file and frontastic-cli-dependencies folder to the root of your repository.

We recommend checking the Frontastic CLI release page regularly to update to the latest version by downloading again and replacing these files.

Then head to the Frontastic studio and bring up a new sandbox. For full steps on how to do this, see the Frontastic sandbox article.

Once you've got that running, you can then follow the rest of the steps in this article below.

Basic usage

❗️

The below steps always require the latest version of Frontastic CLI. Please check you have the latest version installed. Run brew upgrade frontastic-cli to get the latest version or check the Frontastic CLI release page.

🚧

You'll have problems if you run Frontastic CLI in the same checkout as a container/VM. You need to do a clean Git checkout of your project. Also, the Frontastic CLI requires that there's no container/VM with Frontastic running on your local machine when using it.

1. Run frontastic init in the root directory of your code repository checkout

This will iterate you through some questions for generating the base Frontastic CLI configuration:

• Which project do you want to work on? – this will only appear if you have more than 1 project in your folder

• Are you using a Frontastic sandbox or a staging server for development? – select staging server if you're only working on the frontend

You can run frontastic init again at any time if you want to change your configuration.

2. Run yarn install in the root directory of your code repository checkout to get all JavaScript dependencies installed locally

3. Start the local development service using frontastic run

That's it! You'll now see a dashboard where you can find error logs, as well as the URL to your development environment (usually http://<project>-<customer>.frontastic.io.local (basically your staging URL with http:// and .local appended)). You can use the hotkeys on the dashboard to access different information. And when you're done for the day, you can stop the development service by hitting <CTRL>-<C>

Since you're not running a local backend server, any changes to the PHP code or configuration files like project.yml won't have an immediate effect. These changes need to be deployed to staging first. Alternatively, you can use a Bringing up a Frontastic sandbox.

File synchronization

If you need to work on the Backend-for-Frontend, also known as the PHP code, you can enable file synchronization to the remote server. Please note that this only works with a Frontastic sandbox.

To do this:

1. Run frontastic init and select backend file synchronization

2. Start the Frontastic CLI as usual with frontastic run to do frontend development locally and have backend-changes synced to the remote machine or to only start the sync to the remote machine

You can change this configuration any time by again running frontastic init.

You can then use the Frontastic CLI dashboard to watch for filesync errors and look into the issue.

If you want to add custom filesync rules, you can set up an alternative configuration using the flag --mutagenConfig. For example, if you created your own YML configuration file called my-mutagen.yml, you would run frontastic run --mutagenConfig ./my-mutagen.yml.

Dependency management (Composer) with filesync

To make synchronizing code between your localhost and the remote Frontastic sandbox as simple (and therefore resilient as possible) we decided to synchronize one-way as much as possible. Therefore, dependencies must be managed on the remote host.

To install or remove PHP packages do the following:

1. SSH into the Frontastic sandbox using ssh [email protected]<your-machine-host>
2. cd into your project directory (for example, cd demo_english)
3. Run the corresponding composer command there (see getcomposer.org)

The composer.json and composer.lock files will then be synchronized downstream to your code checkout so that you can commit any changes.

If you're working with frontend code remotely, the procedure is the same using yarn.

Troubleshooting

If you're having any issues with the Frontastic CLI, see our Frontastic CLI troubleshooting article or the filesync troubleshooting article.