Fusox

Fusox is the build tool for your typescript projects. It is built on top of the fantastic fuse-box. For detailed information about it features and limitations checkout fuse-box docs.

Take a look at the examples repository for some sample project setups.

Table of Contents

• Purpose
• Installation
• Quick Start
• Scaffolding
• Environment Variables
• CORS Proxy
• JavaScript Usage
• Commandline Usage

Purpose

Every sophisticated project starts with a tedious build process setup. There are many scaffolding tools with templates for every possible use case out there. The problem is - every template is maintained by a different developer, contains opinionated defaults, forces you into a usually complex project structure, is not always up to date, etc. More often then not, all you want is a simple oneliner that gets you up and running, without forcing you to adhere to certain conventions too much. Even better if it's a production ready oneliner that takes care of all the boring stuff necessary for a production build.

I thought - why not build a straightforward build-tool for all of my project needs. Here we are, it works, saves me lots of time and makes my fellow devs happy :)

Installation

npm install --save-dev fusox

Quick Start

Build for browser, watch for changes, start a cors proxy and open app in the browser:

fusox src dist --browser --run --open --cors

Build for electron, watch for changes, launch app in electron and in browser:

fusox src dist --electron --run --open

Build for server, watch for changes, run app trough node:

fusox src dist --server --run

Combine multiple builds into one process:

fusox \
  browser-src:browser-dist:--browser:--run:--open \
  server-src:server-dist:--server:--run

Scaffolding

You must install fusox globally first:

npm install -g fusox

Now can scaffold a sample project for various targets by running one of the commands below:

fusox --init browser
fusox --init electron
fusox --init server
fusox --init library

This will setup a sample project inside current directory, install all the necessary dependencies and launch a dev server.

You can specify the target directory with a second argument:

fusox --init browser cool-app

Environment Variables

Simply create a .env file inside your project's root directory. Additionally you may split your configuration across multiple files, they will be parsed in this order:

• .env.dist default configuration goes here, is checked into git, no sensitive data
• .env local configuration overrides, not checked into git, may contain sensitive data
• .env.(development|production) local, environment specific overrides, controlled by --production and --development flags

Additionally, besides the .env files inside your project's root directory, .env files from your project's source directory are loaded in the same order. This is useful for projects that contain multiple applications and gives your a lot of flexibility.

CORS Proxy

Fusox comes with a cors proxy built in, you can enable it by setting the --cors flag, for browser and electron targets. All ajax and fetch requests are automatically routed trough the cors proxy server. Works only in development mode.

JavaScript Usage

Fusox exposes a simple js api that is almost identical to it's CLI api, below is a simple example in both formats:

const fusox = require('fusox')
 
// simple build
fusox('src', 'dist', {target: browser, run: true, cors: true, open: true})
  .then(() => console.log('done'))
 
// multi build
fusox([
  ['src1', 'dist1', {target: browser, run: true, cors: true, open: true}],
  ['src2', 'dist2', {target: browser, run: true, cors: true}],
])
  .then(() => console.log('all done'))

The same build trough cli:

# simple build 
fusox src dist --target browser --run --cors --open
 
# multi build 
fusox \
  src1:dist1:--target=browser:--run:--cors:--open \
  src2:dist2:--target=browser:--run:--cors

Commandline Usage

Below is a snapshot of the fusox --help output:

Usage: fusox <source> <destination> --options

Version: v2.7.0

Notes:
  - PostCSS and TailwindCSS are transparently available inside all supported css dialects
  - You can override several config files by placing them either inside your current
    working directory or inside the parent directory of your source

      - tsconfig.json   Custom typescript configuration
      - postcss.js      Custom postcss configuration
      - tailwind.js     Custom tailwindcss configuration

Arguments:
  <source>          Path to source files directory
  <destination>     Path to build directory

Options:
  -v, --version     Show cli version
  -h, --help        Show help text
  -d, --docs        Open documentation in browser
  -e, --examples    Open examples in browser
  -i, --init        Scaffold project for various targets inside current directory,
                    target defaults to "browser", see "--target" for available targets,
                    destination defaults to current directory, you can specify different
                    destination directory like this: "fusox --init browser demo"
  -t, --trace       Dump long stacktrace in case an error occurs, defaults to "false"
  --port            Set dev server port, default is "9999"
  --target          Set build target either to "browser", "server", "electron" or "library"
  --browser         Set build target to "browser", same as "--target=browser"
  --server          Set build target to "server", same as "--target=server"
  --electron        Set build target to "electron", same as "--target=electron"
  --library         Set build target to "library", same as "--target=library"
  --mode            Set build mode either to "development" or "production",
  --development     Set mode to "development", same as "--mode=development"
  --production      Set mode to "production", same as "--mode=production"
  --sourcemaps      Generate sourcemaps, enabled in "development" mode by default
  --cache           Use cache to speed up build, enabled in "development" mode by default
  --watch           Watch for changes and rebuild
  --env             Parse ".env" files in cwd and source directories in this order,
                    ".env.dist", ".env" and ".env.(development|production)",
                    enabled by default
  --cwd             Override current working directory, defaults to "process.cwd()"
  --clean           Delete previous build and cache

Options for --browser | --target="browser":
  --run             Run dev server and watch files for changes
  --main            Set main file for your application,
                    defaults to "index.ts" or "index.tsx"
  --index           Set index.html file template, use $css and $bundles placeholders
                    for injection, defaults to "index.html"
  --open            Open web page in browser after build
  --uglify          Uglify code in "production" mode, enabled by default
  --hash            Hash generated files names, enabled in "production" mode by default
  --name            Publish --main entry point under a package name on the window
  --cors            Launch a CORS proxy server, all ajax and fetch requests will be
                    routed trough cors proxy server, works only in "development" mode
  --assets          List of file extensions that should be processed as assets,
                    defaults to "jpg,png,gif,svg,txt,html", you can either override
                    this values or append new ones by putting a "+" at the beginning
  --dynamic         List of file extensions that are imported dynamically in your code
                    and should always be included into your bundle, since you never know
                    which files you may need, defaults to "json,yml,txt", you can either
                    override this values or append new ones by putting a "+" at the beginning

Options for --electron | --target="electron":
  --run             Run dev server and watch files for changes
  --main            Set main file for your application, defaults to "index.ts"
  --index           Set index.html file template, use $css and $bundles placeholders
                    for injection, defaults to "index.html"
  --renderer        Set renderer file for your application,
                    defaults to "renderer.ts" or "renderer.tsx"
  --open            Open application exposed trough a web server,
                    useful for testing hybrid apps
  --uglify          Uglify code in "production" mode, enabled by default
  --hash            Hash generated files names
  --name            Publish --renderer entry point under a package name on the window
  --cors            Launch a CORS proxy server, all ajax and fetch requests will be
                    routed trough cors proxy server, works only in "development" mode
  --assets          List of file extensions that should be processed as assets,
                    defaults to "jpg,png,gif,svg,txt,html", you can either override
                    this values or append new ones by putting a "+" at the beginning
  --dynamic         List of file extensions that are imported dynamically in your code
                    and should always be included into your bundle, since you never know
                    which files you may need, defaults to "json,yml,txt", you can either
                    override this values or append new ones by putting a "+" at the beginning

Options for --server | --target="server":
  --run             Run dev server and watch files for changes
  --main            Set main file for your application, defaults to "index.ts"
  --uglify          Uglify code in "production" mode, enabled by default
  --hash            Hash generated files names
  --assets          List of file extensions that should be processed as assets,
                    defaults to "jpg,png,gif,svg,txt,html", you can either override
                    this values or append new ones by putting a "+" at the beginning
  --dynamic         List of file extensions that are imported dynamically in your code
                    and should always be included into your bundle, since you never know
                    which files you may need, defaults to "json,yml,txt", you can either
                    override this values or append new ones by putting a "+" at the beginning

Options for --library | --target="library":
  --main            Set main file for your library, defaults to "index.ts"
  --module          Set module format that you want to achieve, either "esm", "cjs" or "web"
                    You can provide either a single module format or a comma separated list of formats
                    Different module formats are meant for use in different situations:
                      - "esm" is useful when used together with other esm modules
                        that are processed by a bundler like rollup, webpack or fusox,
                        contains no dependencies, needs to be transpiled at some point
                      - "cjs" can be used directly within any nodejs applicaton,
                        dependencies are not bundled and will be resolved trough
                        node's require(...) function
                      - "web" is a bundle that can be used inside the browser,
                        all the necessary dependencies are also bundled
  --esm             Set module format to "esm", same as --module=esm, no bundling
  --cjs             Set module format to "cjs", same as --module=cjs, no bundling
  --web             Set module format to "web", same as --module=web, generates a bundle
  --all             Set module format to "esm", "cjs", "web", same as --module=esm,cjs,web
  --uglify          Uglify "web" bundle in "production" mode, enabled by default
  --name            Publish --main entry point under a package name on the window, for "web" module