🏗🏗 flipbox

the builder, of builders.

It allows you to create configs that would take hundreds or thousands of lines, with just a few properties.

all you need

minimal

import FlipBox from 'flipbox'
new FlipBox({entry: './src/index.js'}).fullAuto()

all the apps

one app? two apps? 100 apps? nodejs server, inferno, react, fusebox, and webpack? existing configs? happy and no happy pack? at the same time? no sweat.

const FlipBox = require('flipbox')
const apps = [
  {
    name: 'reacted',
    config: './webpack.config.js'
    fusebox: true,
  },
  {
    name: 'infernod',
    entry: './src/index.js',
    presets: ['inferno'],
    html: './src/index.html',
  },
  {
    name: 'backend',
    entry: './backend/src',
    presets: ['node'],
    happypack: false,
  },
]
module.exports = new FlipBox({apps}).fullAuto()

reusability?

const FlipBox = require('flipbox')
const apps = [
  {
    name: 'reacted',
    presets: ['react', 'entry'],
  },
  {
    name: 'infernod',
    presets: ['inferno', 'entry'],
  },
]
module.exports = new FlipBox({
  apps,
  presets: {
    front: {
      entry: './src/index.js',
      html: '#root',
      fusebox: true,
    },
  },
}).fullAuto()

...oh and you can run those configs through webpack just like any other webpack config. which means you can also change the returned config in the same way.

[they are configured for each environment by default](#-default settings)

and can be customized for any config you want

it can build itself with webpack or fusebox, with the flip of an env flag

the problem

• build systems are notorious for their difficulty.
• finding and setting up the right
  • scripts
  • plugins
  • loaders
  • configs
  • requiring the dependencies
  • bloating your config files
  • making configs for
    • development bundling
    • production bundling
    • production dev bundling
    • test environments
    • development servers
    • production servers
• tedious, with a high barrier of entry
• time intensive; switching build systems for 1 app is grueling
• ... all of the above for every application

the solution

• with the flip of a flag, you can go from webpack, to fusebox, or any other supported build system.
• existing webpack configs can be used and enhanced with ease.
• create plugins to start converting your build system to another, flip the switch to keep compatibility without breaking everything,

legend

• middleware
• apps
• commander
• examples
• terminology
• 🏭 behind the scenes / internal

examples

• examples-basic
• examples-basic-build
• examples-compat 🚧
• examples-flipbox
• examples-fuse-canadas
• examples-fusebox
• examples-intermediate
• examples-intermediate-tests 🚧
• examples-verbose

⚠

• needs cleaning
• needs general improvements
• needs more thought in running them all
• todo-examples

🔌 middleware

add your own middleware

• you can add your own middleware before building apps
• the name of the middleware maps in as a hook for the properties on the app
• optional index property to insert middleware at any position
• middleware interface

example

flipbox.addMiddlewares({
  index: 999, // optional
  name: 'propertyOnApp',
  inject(app, helpers) {
    helpers.log.text('❗ middleware for `.propertyOnApp`!')
    return app
  },
})

⚠

• todo-middleware

🐛 debugging

• ⚙ with full options for debugging everything in the flipping process, debugging is a breeze.
• see debugging - deep for all of the options

🏹 aliasing

problems

• relatively importing files is a major pain ../../../../../utils
• when refactoring, relative imports requires updating all files affected
• manually resolving paths to root
  • bloats the code
  • adds knowledge about the structure to files that should not need it, such as presentation layer / ui components
• multiple versions of any npm packages
  • multiple react refs when multiple versions of react are loaded
  • dependencies have different versions of the same dependency
  • servers such as heroku keep caches where there are multiple versions

solutions

• using aliases, you can force a single version of a dependency
• write your aliases relatively to your home

🔗 resources

• 🗼 babel aliases
• 🕸 webpack aliases
• 💣 fusebox aliases
• ✔️💣🕸

🍰 presets

add your own presets

.extendPresets({
  'inferno': {
    loaders: ['styleloader'],
    alias: ['moose', 'igloo', 'inferno'],
    html: '#root',
  },
})

built in presets

• built in presets

🍦 default settings

• see the code

default defaults

{
  env: {
     production: {
       uglify: true,
       defineProduction: true,
       run: false,
       compile: true,
       useSourceMaps: false,
       sourceMapTool: 'hidden',
     },
     development: {
       noEmitErrors: true,
     },
  }
}

adding your own defaults

this would make it so if fusebox flag are true, it would add the fusebox property to any app that has passed filters and is being built.

flipbox.addDefaults({
  flags: {
    // this can also be a objects,
    // or an array of strings
    // or a string
    names: [{flag: 'fusebox', type: 'bool', default: false}],
    cb: ({fusebox}) => {
      return {fusebox}
    },
  },
})

⚠

• ✔️💣🕸
• needs docs
• todo-presets

params

• converts shorthand code to webpack configs
• read the code
• ✔️💣🕸

💣🛅 fusebox

• converts webpack configs to fusebox configs
• read the code
• ✔️💣
• todo-build-systems
• needs to pass in more of the config

☺️️🛅 happypack

• happypack
• ✔️🕸

defaults

happypack: {
  cache: false,
  threads: 4,
  include: [
    './',
  ],
}

{
  _noop: true,
  clean: false, // bool, or array<string>
}

🗺 sourcemaps

• ✔️💣🕸

defaults

env: {
  development: {
    useSourceMaps: true,
    sourceMapTool: '#source-map',
  }
  production: {
    useSourceMaps: true,
    sourceMapTool: 'hidden',
  },
}

⚖️ loaders

• ✔️💣🕸
• .loaderOptions

defaults

loaders: {
  'babel': {},
  'json': {},
},

🚩 flags

flags can be used to find global variables passed around for configuration from globals

defaults

flags: {
  names: [
    {flag: 'compile'},
    {flag: 'exec'},
    {flag: 'run'},
    {flag: 'test'},
  ],
  cb: ({compile, exec, run, test}) => {
    var decorated = {compile, exec, run, test}
    if (test) {
      if (decorated.presets) {
        decorated.presets.push('test')
        decorated.presets.push('mocha')
      }
      else decorated.presets = ['test', 'mocha']
    }
    // helpers.log.verbose(decorated)
    return decorated
  },
}

examples

flags: [
  {
    names: ['html'],
    cb({html}) {
      if (!html) return {}
      var template = `./back/verbose/${html}.html`
      return {html: [{template}]}
    },
  },
  {
    names: [{flag: 'run', type: 'bool', default: false}],
    cb({run}) {
      return {run}
    },
  },
],

resources

• yargs
• node-flag
• ✔️💣🕸

⚠

• needs ungreedy search
• todo-flags

♼ environment

is an extension of flags as a middleware using flags

defaults

env: {
  production: {
    uglify: true,
    defineProduction: true,
    run: false,
    compile: true,
    sourceMaps: false,
    sourceMapTool: 'hidden',
  },
  development: {
    noEmitErrors: true,
  },
}

☕🏳️ filters

white flags are used to filter which apps are run for different operations

apps, and app operations can be filtered based on flags either per app, or for all apps. see the examples

configOut

• writes the generated config to a file, for use with babel-module-resolver
• ✔️💣🕸

polyfills

• can be used currently only for polyfilling window when you .exec in app operations

⚠

• ✔️🕸
• needs docs
• todo-polyfill

externals

• allows you to exclude paths from a bundle
• ✔️💣🕸
• webpack externals
• fuse exclude

tests

• run tests in mocha
• run tests in karma
• ^ while running dev servers at the same time

⚠

• ✔️💣🕸
• needs docs
• needs links to code
• needs links to karma and mocha
• todo-tests

👑⚔️ commander

resources

• commanderjs

⚠

• needs docs
• needs lots of work
• todo-commander

apps

• multiple apps flow-app

app-operations

• 🏃🏸 running
  • 🔮🌐 automatic safety in ports
• ⌛ compiling
  • 👂 compileEnd
• 💀 executing
• 👻 mediator
• ⛴ releasing scripts
  • 📦🏗 package builder
  • pipeline
  • task running
  • 💚📜 scripts created for ci environments
  • 🔮📜 scripts for all environments and servers created and added to your packages
  • 📦⬇ keep your dependencies at root to avoid symlinks and massive package sizes

⚠

• needs docs

🕳 digging deeper

🖇 helpers

🐛 deep-debugging

• 🎨 logs are styled with color & emoji for easy searchability & scannability
• 👀 full source options, when you want to see deep inside the contents, you can
  • log.verbose for node util inspected colored logs
  • log.source for tosource logs of the contents
  • log.color for [any supported color][chalkjs] as the log level
  • log.text.color for any supported color for entire log

defaults

debug: {
  missingMiddleware: false,
  missingLoaders: true,
  devServer: true,
  middleware: true,
  loaders: false,
  verbose: false,
  built: false,
  decorated: true,
  time: true,
  filter: true,
  defaults: false,
  happypack: false,
  presets: false,
  out: true,
  order: false,
  params: false,
  alias: true,
  fuse: true,
  exec: true,
  flags: true,
  testOutput: true,
}

⚠

• todo-helpers#log

📒 files

• write
• read(dir)
  • synchronously reads a file as a string
• isFile(file)
  • returns boolean
• getFileAndPath(file)
  • splits up a path
  • returns {file, path}
• resolving
  • root
  • forKeys
  • isAbsolute

⚠

• needs types

🌐 port

used for finding available ports if preferred ones are not available

⚠

• needs types
• needs option to disable

html

example

{
  flags: {
    // selector=your-custom-root-react-id
    // htmlfile='./src/index.html'
    // htmlfiles=['./src/index.html', './src/page2.html']
    // template=[{template: './src/index.html'}]
    names: [
      'selector',
      'htmlfile',
      'template',  
      {flag: 'htmlfiles', type: 'array'},
    ],
    cb: ({selector, htmlfile, template, htmlfiles}) => {
      if (selector) return {html: `#${selector}`}
      if (htmlfile) return {html: htmlfile}
      if (htmlfiles) return {html: [htmlfiles]}
      if (template) return {html: template}
    },
  },
}

⚠

• ✔️🕸
• needs docs
• needs more fusebox support, only supports html file

📚🚧 (need docs)

• HMR
• include
• builderInstance
• init
• instructions
• tasks
• copy
• define
• uglify
• analyze
• clean
• provide

🗝️⎁ terminology / key

home

• fusebox-homedir
• webpack-root

⚠

• docs need work
• code needs work
• 💣🛅 fusebox compatible
• 🕸🛅 webpack compatible

🏭 behind the scenes

core

middleware

• flattening

builders

core

🖇 helpers

reference & context

📅 plans

• todo-architecture
• todo-later-soon-next
• todo-perf

⚠

• needs docs

🏗 build systems / builders

• fusebox

  app = {
    fusebox: false,
    fuseboxAlias: false,
  }

• webpack - is default

🎃 tips n tricks

• 🚧 this is a wip, it has been in development for about a week and as such is not 100% stable, but is definitely worth trying