node package manager

flip-box

🏗🏗 flipbox

Build Status Fusebox-bundler NPM version Dependencies

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

legend

examples

  • 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
  },
})

🐛 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

🍰 presets

add your own presets

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

built in presets

🍦 default settings

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}
    },
  },
})

params

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

💣🛅 fusebox

☺️️🛅 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

♼ 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

polyfills

externals

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

apps

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

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,
}

📒 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

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

🏭 behind the scenes

## core ## middleware

  • flattening

## builders ## core

## 🖇 helpers reference & context

📅 plans

  • 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