about

docs

pricing

oss

consulting

Appearance

Command Line Interface


Page:
/development


Overview

First, make sure you have the cli installed.

copied!

$ npm install -g floro



Next, run:

$ floro --help


this should output the following:

Commands:
floro start Start the floro daemon
floro kill Kill the floro daemon
floro restart Restart the floro daemon
floro login Login to floro via cli
floro logout Logout from floro via cli
floro create-generator [generator] Generates floro generator scaffolding
floro create-plugin [plugin] Generates floro plugin scaffolding
floro module Build application state from repository
floro generator Generator development commands
floro plugin Local plugin development commands

Options:
--version Show version number
--help Show help


BETA Notice

While all the commands exist for you to develop plugins & generators of your own. The CLI tools for plugins and generators are still a work in progress. We have not stabilized the CLI API yet.

We will release documentation in the coming weeks for building your own plugins & generators. Feel free to build but build at your own risk.



$ floro module

The only command you need to get started for using floro in your own project is floro module.

$ floro module --help


should output:

Build application state from repository

Commands:
floro module sync Syncs state to meta file
floro module build Builds application state from floro repository
floro module watch Watch floro state and rebuild
floro module current Use current state and rebuild

Options:
--version Show version number
--help Show help
-m, --module Specify the floro module script
-k, --remote-key Specify a remote api key to pull with (only needed if logged out)
-l, --local Syncs meta file with state from local repository


What is a floro.module.js file?

const paletteGenerator = require("@floro/palette-generator");
const themesGenerator = require("@floro/themes-generator");
const iconGenerator = require("@floro/icon-generator");
const textGenerator = require("@floro/text-generator")

module.exports = function () {
  return {
    repository: "@floro/floro-mono", // this points to your floro repository
    // branch: "main", (branch defaults to "main", but you could point to any branch)
    generators: [
      {
        generator: iconGenerator,
        args: {
          lang: "typescript",
        },
      },
      {
        generator: themesGenerator,
        args: {
          lang: "typescript",
        },
      },
      {
        generator: paletteGenerator,
        args: {
          lang: "typescript",
        },
      },
      {
        generator: textGenerator,
        args: {
          lang: "typescript",
        },
      },
    ],
  };
};


Your floro.module.js ties your codebase to your floro repository. By convention, it should be in a floro_infra directory.

When you build from floro, your floro.module.js will pull the state from your repository and pass the raw repository state into the generators you specify. It is also used to sync your codebase to a given commit state. When you sync your state, the floro.module.js will be used to create a meta.floro.json file.

An example of a meta.floro.json output from syncing may look like the following.

{
  "moduleFile": "floro.module.js",
  "repositoryId": "12aa1618-9e0b-404c-8423-7c38047e18c9",
  "sha": "892bdc97a7f4f26c7ede62edb8591c44d1afd561a6d94c41c81a8ee48e9b3a52",
  "message": "updated docs",
  "idx": 95,
  "generatorDependencies": {
    "icon-generator": {
      "icons": "0.0.40"
    },
    "themes-generator": {
      "theme": "0.0.40"
    },
    "palette-generator": {
      "palette": "0.0.39"
    },
    "text-generator": {
      "text": "0.0.32"
    }
  }
}


Both your floro.module.js and meta.floro.json files should be checked into your code source control system. However, the generated floro_modules directory should be gitignored.

When floro builds assets in your code base, it uses the meta.floro.json file to know which commit to use in order to build the code assets from (explained in greater depth below).

floro module common args & flags

You should run these commands from a floro_infra directory. Otherwise you can use the --module (-m) argument to point at your floro.module.js file from a relative path.

By default sync and build will use your remote repository state.

To specify that you want to sync from your local repository, you need pass in the --local (-l) flag.

If your repository is private, you may need to specify a remote api-key that has access to the repository. This comes up often in CI/CD.

To specify an api-key, add the --remote-key (-k) flag to your sync command. You can also use the global env var FLORO_REMOTE_API_KEY if you do not specify an api-key in the command.



$ floro module <command>


(see demos from integration docs for an in depth explanation)

sync

The sync command pulls the commit state from your repository. If you specify the --local flag (-l), you will pull the commit state from your local repository. The --build (-b) builds your state after syncing (see next section on build).

Sync directly modifies your meta.floro.json file if successful.

build

The build command uses the meta.floro.json to pull the state from your repository. If you specify the --local flag (-l), you can point to commits that are stored locally (even when the commit has not been pushed to the remote repository yet).

Build uses the generators specifies in your floro.module.js to generate code and assets in the floro_modules directory.

post-processing (build)

The build command will look for a file next to floro.module.js called postprocess.floro.js. If the file is present, additional modifications to the floro_modules can be made from the postprocess.floro.js script. This is a good place to perform tasks like static-analysis.

current

The current command builds your floro_modules from the present WIP state on your local machine. This is really useful during development. When using current you have to remember to commit, push your floro changes to the remote, and sync against your remote repository before you push your code. Your build server will not be able to pull from your local repository, so this is one important aspect to keep in mind.

watch

The watch command is very similar to the current command, however, watch will run every time you make a change to your local repository. This can be useful if you are working on a repository without hot module reloading (HMR), however, it is most likely a better developer experience to just use the floro browser extension and use floro module current to build your modules during development.