FuseBox Bundler

Common errors

• Missing semicolon messed up with UMD init

  cause A bug in FuseBox's UMD build output.
  fix Upgrade to FuseBox v3.2.2 or later, which includes a fix for this issue.

• Domain polyfill syntax error

  cause An incorrect syntax within the domain polyfill bundled by FuseBox.
  fix Upgrade to FuseBox v3.7.0 or later to get the fix for the domain polyfill syntax error.

• ReferenceError: process is not defined (during Quantum build)

  cause Older versions of FuseBox's Quantum plugin might not correctly handle global `process` or `process.env` variables during optimization, leading to runtime errors in client-side bundles.
  fix Upgrade to FuseBox v3.6.0 or later, which includes a fix for `process` and `process.env` handling in Quantum builds.

• CSSResourcePlugin backslashes fixes on Windows 10 (or similar path issues)

  cause Path handling inconsistencies, particularly with backslashes on Windows, affecting resource resolution in CSS.
  fix Upgrade to FuseBox v3.2.2 or later, which includes fixes for CSSResourcePlugin path issues on Windows. Ensure consistent path separators in your configuration.

Warnings

• breaking The FuseBox project's official GitHub repository (`fuse-box/fuse-box`) was archived on June 20, 2023, and is now read-only. This signifies that the project is no longer actively maintained or developed, and no further updates, bug fixes, or security patches will be released. Users should consider migrating to actively maintained alternatives.
  Fix: Migrate to an actively maintained bundler like Webpack, Rollup, Parcel, or Vite.
• breaking FuseBox v4.0.0 introduced a fundamental shift in configuration, moving from programmatic JavaScript/TypeScript files (like `fbx_switch.js`) to an XML-based system, requiring `fusebox.xml` and `circuit.xml` files. This is a significant breaking change; existing v3 configurations are incompatible with v4.
  Fix: Rewrite your FuseBox configuration using the new XML schema as described in the v4 documentation, or stick to FuseBox v3.x and consider migration due to project abandonment.
• gotcha Older Node.js versions might not be compatible. The `package.json` specifies `"node": ">= 6.9.5"`, but due to project abandonment and lack of updates, newer Node.js versions might introduce unforeseen compatibility issues.
  Fix: Refer to the `engines` field in `package.json` for compatible Node.js versions. For abandoned software, it's safer to use the Node.js version contemporary with its last active development.
• gotcha Some internal polyfills have changed in minor versions (e.g., `stream-browserify` was added, `uws` was replaced with `ws`). If your application relied on specific behaviors or had conflicts with these polyfills, updates could introduce subtle bugs.
  Fix: Carefully review changelogs for minor versions before upgrading and test thoroughly, especially concerning network and stream-related functionalities.

Install

• npm install fsbx npm
• yarn add fsbx yarn
• pnpm add fsbx pnpm

Imports

• FuseBox
  wrong:

  import { FuseBox } from 'fuse-box';

  correct:

  const { FuseBox } = require('fuse-box');

  Configuration files are primarily CommonJS (Node.js) using `require` for instantiating the bundler, especially in v3. While ES module `import` might be used in application code, the bundler configuration itself typically uses `require`.
• WebIndexPlugin
  wrong:

  import WebIndexPlugin from 'fuse-box/plugins/WebIndexPlugin';

  correct:

  const { WebIndexPlugin } = require('fuse-box');

  Plugins are exposed as named exports from the main `fuse-box` package. The `plugins` directory is not typically imported directly.

Quickstart

This quickstart demonstrates how to configure FuseBox for a basic TypeScript project, including setting up a development server with Hot Module Replacement (HMR) and a production build with minification and HTML generation. This configuration style is typical for FuseBox v3.x.

import { FuseBox, WebIndexPlugin, CSSPlugin, QuantumPlugin } from "fuse-box";
import * as path from "path";

async function bundleApp() {
    const isProduction = process.env.NODE_ENV === "production";

    const fuse = FuseBox.init({
        homeDir: "src", // Your source code directory
        output: "dist/$name.js", // Output bundled files to dist/
        target: "browser", // Target browser environment
        hash: isProduction, // Add hash to filenames in production
        plugins: [
            CSSPlugin(), // Process CSS files
            WebIndexPlugin({ template: "src/index.html" }), // Generate index.html
            isProduction && QuantumPlugin({
                uglify: true, // Minify JavaScript
                css: true, // Minify CSS
            }),
        ].filter(Boolean),
        log: !isProduction,
        debug: !isProduction,
    });

    // Setup development server with HMR for non-production builds
    if (!isProduction) {
        fuse.dev({ port: 4444, httpServer: true });
        fuse.bundle("app")
            .instructions(`>index.ts`) // Entry point
            .hmr() // Enable Hot Module Reloading
            .watch(); // Watch for changes
    } else {
        // Production bundle
        fuse.bundle("app")
            .instructions(`>index.ts`);
    }

    await fuse.run();
    console.log("FuseBox bundling complete!");
}

bundleApp().catch(console.error);

// To make this runnable, ensure you have:
// 1. A 'src' directory with 'index.ts' (e.g., console.log("Hello from FuseBox!");)
// 2. A 'src/index.html' (e.g., <body><div id="root"></div></body>)
// 3. Run with `NODE_ENV=development ts-node fuse.ts` or `NODE_ENV=production ts-node fuse.ts`