@arc-fusion/cli

CLI for running Arc Fusion on your local machine

Usage no npm install needed!

<script type="module">
  import arcFusionCli from 'https://cdn.skypack.dev/@arc-fusion/cli';
</script>

README

Arc Fusion CLI

This is the CLI tool for running Arc Fusion on your local machine.

Changelog

You can see the changelog here. You will need to be logged into Okta and have access to Arc Learning Center (ALC).

Requirements

The following apps/commands are required for the fusion CLI to function properly:

  • node - This should be the same version of Node your FUSION_RELEASE is using (v10 in 2.7.x and earlier, v12 in 2.8.x, and v14 in 3.0+)
  • npm - This should be the default version provided by node (v6 in Node 14 and earlier, v7 in Node 16+)
  • docker 17.06+
  • docker-compose

Installation

Global install

npm install -g @arc-fusion/cli

will install a command-line script on your system, globally accessible as fusion.

Local install

npm install --save-dev @arc-fusion/cli

will install a command-line script in your repo, locally accessible as npx fusion or npm run fusion.

Testing

To test the CLI, you can either use npm link in the local folder and npm link @arc-fusion/cli in the repo or you can run npm install --no-save [path to local folder] in the repo where you want to test it out. Then just run the command you need to test with npx fusion <command>.

Publishing

First, make sure you have read/write access for the @arc-fusion org, as well as the cli repo itself at https://www.npmjs.com/package/@arc-fusion/cli. If you haven't already, enable Two-Factor Authentication, because by default we have the setting to require 2FA for modifying the module. Make sure you have also logged into your npm account through the npm cli with the one that has access to the @arc-fusion org.

For releasing a new version, run npm run stable and it will strip the prerelease version, publish it, and tag it with stable and latest. You should use npm run canary and npm run beta to generate new prerelease versions (no version increase). You should use npm run canaryPatch, npm run canaryMinor, and npm run canaryMajor to increment the version for the current prerelease.

When creating a new stable/latest version, make sure you update the changelog in the answers org.

Linking

If you are using another npm package and need to test local changes, you will need to use npm link. Follow the steps below to understand how to do this.

  1. Make sure your node and npm version matches the version used by the FUSION_RELEASE image
  2. Go to the folder containing your package and npm npm link
  3. Go to the folder containing your bundle and run npm link [package name]
  4. If this package is published, make sure it is in the dependencies object in your package.json file
  5. If this package is not published, add it to the devDependencies object in your package.json file manually (don't use npm i -D), and save it
  6. Start fusion via npx fusion start

Commands

All commands should be run from within the repository, as fusion <command> if installed globally, or npx fusion <command> if installed locally.

daemon [--no-admin]

Run Fusion services in detached mode

down

Stop and remove containers, networks, images, and volumes

dump

Export the database into data/dumps/<timestamp>.tar.gz

init

Initialize the directory as a git repo, an npm package, and bootstrap the fusion directory structure

migrate

Migrate a legacy fusion repository to work with the fusion CLI

rebuild

Force a webpack rebuild of a running cluster

start [--no-admin]

Configure a docker-compose cluster to map npm linked modules, then start services.

This is also aliased as npm start for convenience.

The start command may also be run with the --no-admin flag to run the rendering services without the admin app.

If FUSION_REPO is set in the .env file of the repo, the local version of fusion will be used for development. This should be the absolute path to the directory the local fusion repo is in.

For themes development, there are a few additional flags you can use:

  • -l or --links: Use the local version of blocks for developement. Can optionally take a comma separated string of blocks to link instead of linking all of them (-l @org/block1,@org/block2). This requires that you have THEMES_BLOCKS_REPO set in your .env file and it should be the absolute path to the directory the local blocks repo is in.
  • New for fusion 2.7.4 When linking an unpublished block, you will need to include @org/block-name@local in your blocks.json in addition to using the -l @org/block-name flag.
  • -f or --rebuild: Rebuild the webpack image and pull the latest version of the blocks.
  • -p or --production: Force the image to use the published blocks. A developer can use any published tag canary, beta, stable, hotfix, or latest.

We also allow a few additional environment variables (set in the repo's .env file):

  • ENGINE_SDK_REPO: This is used only for themes development. If set, this will use the local version of the engine sdk for development. This should be the absolute path to the directory the local engine sdk repo is in.
  • CSS_FRAMEWORK_REPO: This is used only for themes development. If set, this will use the local version of the css framework for development. This should be the absolute path to the directory the local css framework repo is in.
  • BLOCK_DIST_TAG: This is used only for themes development. If set, this will control the version of all installed blocks that don't specify a version. The default is stable.
  • ENGINE_HEAP_SIZE: If set, this changes the amount of memory (in MB) the engine image's node is allowed to use. The default is 2048.
  • WEBPACK_HEAP_SIZE: If set, this changes the amount of memory (in MB) the webpack image's node is allowed to use. The default is 4096.
  • FUSION_RELEASE: If set, this changes the version of Fusion used for the engine and webpack images. The default is latest.
  • PORT: If set, this changes the port Fusion uses. The default is 80.
  • DEBUG: If set, this changes the logs you can see in the terminal. The default is arc.fusion.render.error (only log rendering errors). You can set it to * to see all logs.

There are a few environment variables you can use for testing/troubleshooting. We don't recommend setting these unless you know what you are doing/were directed to do so by support.

  • ENGINE_SDK_DIST_TAG: This is used only for engine sdk in themes development. If set, this will control the version of engine sdk dependencies in blocks that don't specify a version.
  • CSS_DIST_TAG: This is used only for CSS frameworks in themes development. If set, this will control the version of CSS frameworks dependencies in blocks that don't specify a version.

stop

Stop services

verify

Run webpack on the repo source to ensure it has no compilation errors

zip

  • -f or --force: Skip verifying the bundle.
  • -n or --rename: Change the generated zip file's name.

Create a zip file that is appropriate for upload into the fusion deployment system