fusox/readme.md

Command line wrapper for fuse-box

# Fusox

Fusox is the build tool for your typescript projects. It is built on top of the fantastic [fuse-box](https://github.com/fuse-box/fuse-box). For detailed information about it features and limitations checkout [fuse-box docs](https://fuse-box.org).

Take a look at the [examples](https://github.com/maximkott/fusox-examples) repository for some sample project setups.

## Table of Contents

- [Purpose](#purpose)
- [Installation](#installation)
- [Quick Start](#quick-start)
- [Scaffolding](#scaffolding)
- [Environment Variables](#environment-variables)
- [CORS Proxy](#cors-proxy)
- [JavaScript Usage](#javascript-usage)
- [Commandline 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:

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

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

```bash
fusox src dist --electron --run --open
```

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

```bash
fusox src dist --server --run
```

Combine multiple builds into one process:

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

## Scaffolding

You must install fusox globally first:

```bash
npm install -g fusox
```

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

```bash
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:

```bash
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:

```js
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:

```bash
# 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
```