Fusion.js CLI

2.39.1 verified Thu Apr 23 auth: no javascript abandoned

The `fusion-cli` is the command-line interface for the Fusion.js framework, designed to orchestrate the development lifecycle of universal React applications. It handles compile-time configurations for both server and browser bundles, facilitating development, testing, and production deployments. Key features include a standardized Babel configuration with modern ECMAScript support, efficient hot module reloading, and an integrated web server. Fusion.js, originally developed by Uber, focuses on high performance, server-side rendering (SSR), and a modular, plugin-driven architecture, enabling seamless transitions between client and server logic. As of the provided npm data, the current version is 2.39.1. However, the last recorded release in the excerpt is from October 2022, and the broader Fusion.js project on GitHub shows minimal recent activity, suggesting a slow or halted development cadence for the framework. It emphasizes a strict, opinionated build process, notably not supporting custom Webpack configurations to maintain internal consistency and facilitate future bundler transitions.

Common errors

error No command given. Type 'fusion help' for more information. ↓

cause The `fusion` command was executed without specifying a subcommand (e.g., `dev`, `build`, `start`).

fix

Run fusion <command> where <command> is one of the available subcommands like fusion dev, fusion build, or fusion start. You can see all available commands with fusion help.

error Cannot read property 'sub' of undefined ↓

cause This error, often seen in Fusion.js applications, typically indicates an issue with a plugin trying to access a property on an undefined object, frequently within context (`ctx`) or a plugin's dependency (`deps`). It suggests a missing dependency, incorrect plugin registration, or an unexpected state in the application context.

fix

Verify that all required plugins are correctly registered using app.register() in your src/main.js or similar entry point. Inspect the stack trace to identify the problematic plugin and ensure its dependencies are satisfied. Check for proper initialization of values within the plugin's provides method.

error Fresh install not working / Unable to install dependencies from fresh clone of master ↓

cause These generic errors often point to issues with package manager versions (Yarn/npm), Node.js version incompatibilities, or underlying build tool problems (like `iltorb` module deprecation as seen in some issues). Fusion.js is a monorepo that historically used Yarn v2 (now Yarn Berry).

fix

Ensure your Node.js, Yarn, and npm versions meet the engines requirements. For Fusion.js projects, ensure you are using the correct Yarn version (historically Yarn v2/Berry) and have run yarn install at the monorepo root. Address any specific dependency installation errors.

error Build completed (printed twice) ↓

cause A known issue where the build completion message is redundantly printed twice in the console output.

fix

This is a minor aesthetic issue and does not generally impact the build process or output. No direct fix for users, as it's an internal CLI behavior.

Warnings

breaking Fusion.js, and by extension `fusion-cli`, does not support custom `webpack.config` files. This is a deliberate design choice to maintain consistency and allow the framework to evolve its internal bundling mechanisms. Any attempts to provide a custom Webpack configuration will be ignored or lead to unexpected behavior. ↓

fix Instead of custom Webpack configurations, leverage Fusion.js's plugin architecture and `.fusionrc.js` for build-time customizations. If a feature is truly missing, consider contributing to the Fusion.js project or creating a feature request.

deprecated The `--testFolder` CLI option is deprecated. Developers should migrate to using `--testMatch` or `--testRegex` for specifying test file locations. ↓

fix Replace `--testFolder <path>` with `--testMatch '<glob-pattern>'` or `--testRegex '<regexp-string>'` in your `package.json` scripts or CLI commands.

gotcha When running Fusion.js applications, the `fusion dev` command builds browser artifacts in memory and does not save them to the filesystem. In contrast, `fusion build` saves artifacts to disk. If you intend to run a previously built application using `fusion start`, you *must* use `fusion build` first; running `fusion start` after `fusion dev` will fail due to missing build artifacts. ↓

fix Always use `yarn fusion build` or `npx fusion build` before `yarn fusion start` for production or staging environments. `yarn fusion dev` is for development with Hot Module Reloading.

breaking Fusion.js CLI version 2.35.0 updated the React dependency to 18.2.0. Applications using older React versions might encounter compatibility issues or require updates to React-related packages and code patterns to align with React 18's changes (e.g., `createRoot`). ↓

fix Ensure your application and all Fusion.js-related plugins are compatible with React 18. Update `react` and `react-dom` peer dependencies accordingly. Review React 18 upgrade guides for potential breaking changes in your application code.

gotcha The `fusion-cli` infers the `NODE_ENV` environment variable from the initiating CLI command and its flags. It cannot be manually configured through environment variables directly and attempts to override it may be ignored or lead to unexpected build outcomes. ↓

fix Rely on the CLI commands (e.g., `fusion dev`, `fusion build --production`) to set the appropriate `NODE_ENV`. If specific build behaviors depend on `NODE_ENV`, ensure they are configured within the `.fusionrc.js` or via plugin options that respond to the CLI-inferred environment.

Install

npm install fusion-cli

yarn add fusion-cli

pnpm add fusion-cli

Imports

App
wrong
```
import { App } from 'fusion-react'
```
correct
```
import App from 'fusion-react'
```
The primary class for instantiating a Fusion.js application, typically a default export from 'fusion-react'.
createPlugin
wrong
```
import createPlugin from 'fusion-core'
```
correct
```
import { createPlugin } from 'fusion-core'
```
Function used to define and create Fusion.js plugins, a named export from 'fusion-core'.

Router

wrong

import { Router } from 'fusion-plugin-react-router'

correct

import Router from 'fusion-plugin-react-router'

A common plugin for routing in Fusion.js applications, typically a default export.

Quickstart

This quickstart demonstrates the core structure of a Fusion.js application using `fusion-cli`, showing app initialization, plugin registration, and a basic custom plugin.

import React from 'react';
import App from 'fusion-react';
import {createPlugin} from 'fusion-core';
import Router from 'fusion-plugin-react-router';
import {SessionToken} from 'fusion-tokens';
import JWTSession from 'fusion-plugin-jwt';

// Define a simple root component
const Root = () => <div>Hello Fusion.js!</div>;

// Create and export the Fusion.js app
export default () => {
  const app = new App(<Root />);

  // Register common plugins like Router and Session
  app.register(Router);
  app.register(SessionToken, JWTSession);

  // Example of a custom plugin logging requests
  const MyPlugin = createPlugin({
    provides() {
      return {
        logMessage: (message) => console.log(`MyPlugin: ${message}`),
      };
    },
    middleware(deps, middleware) {
      return async (ctx, next) => {
        deps.logMessage(`Request received for path: ${ctx.path}`);
        await next();
      };
    },
  });
  app.register(MyPlugin);

  return app;
};