fliphub-monorepo

[travis-image]: https://travis-ci.org/fliphub/fliphub.svg?branch=master [travis-url]: https://travis-ci.org/fliphub/fliphub [flipfam-image]: https://img.shields.io/badge/%F0%9F%8F%97%20%F0%9F%92%A0-flipfam-9659F7.svg [flipfam-url]: https://www.npmjs.com/package/flipfam [nsp-url]:https://nodesecurity.io/orgs/fliphub/projects/d37f0cc6-02ea-4f05-a8aa-3b6c1e08bd21 [nsp-image]: https://nodesecurity.io/orgs/fliphub/projects/d37f0cc6-02ea-4f05-a8aa-3b6c1e08bd21/badge # 🏗💠 fliphub [![Build Status][travis-image]](travis-url) [![NPM version][npm-image]][npm-url] [![fliphub][gitter-badge]][gitter-url] [![Slack][slack-image]][slack-url] [![flipfam][flipfam-image]][flipfam-url] [![Dependencies][david-deps-img]][david-deps-url] [![MIT License][license-image]][license-url] [![Standard JS Style][standard-image]][standard-url] [![NSP Status][nsp-image]][nsp-url] ![examples-badge](https://img.shields.io/badge/📘-examples-blue.svg?style=flat-square) [![PRs Welcome](https://img.shields.io/badge/🌽%20PRs-welcome-EFC052.svg?style=flat-square)](http://makeapullrequest.com) > the builder, of builders. ## all you need enables configs that would take hundreds or thousands of lines, with just a few properties. #### minimal [see the example](example-minimal) ```js import FlipHub from 'fliphub' new FlipHub({entry: './src/index.js'}).build() ``` ## usage ```bash yarn add fliphub npm i fliphub --save ``` ```js const log = require('fliphub') ``` #### all the apps one app? two apps? 100 apps? fusebox, rollup, _and_ webpack? nodejs server, inferno, and react? existing configs? happy and no happy pack? at the same time? no sweat. ```js const FlipHub = require('fliphub') const apps = [ { name: 'reacted', config: './webpack.config.js' flips: {to: 'fusebox'}, }, { name: 'infernod', entry: './src/index.js', presets: ['inferno'], html: './src/index.html', happypack: true, }, { name: 'backend', entry: './backend/src', presets: ['node'], }, ] FlipHub.init({apps}).build() ``` #### reusability? ```js const { FlipHub } = require('fliphub') const apps = [ { name: 'reacted', presets: ['react'], }, { name: 'infernod', presets: ['inferno'], }, ] FlipHub.init({ apps, presets: { front: { entry: './src/index.js', html: '#root', fusebox: true, }, }, }).build() ``` [they are configured for each environment by default](#-default settings) [and can be customized for any config you want](#-flags) [it can build itself with webpack, fusebox, or rollup, with the flip of an env flag][src-pkg-json] ## the problem - [build systems are notorious for their difficulty][medium-webpack-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](#flags), you can go from [webpack][webpack], to [fusebox][fusebox], or any other supported build system. - [existing webpack configs](#compat) can be used and enhanced with ease. - [create plugins](#create-your-own-plugins) to start converting your build system to another, flip the switch to keep compatibility without breaking everything, # 🗝️ legend - [middleware](#-middleware) - [apps](#-apps) - [commander](#-commander) - [examples](#-examples) - [terminology](#-terminology) - [🏭 behind the scenes / internal](#-behind-the-scenes) # 📘 examples - [examples-minimal][examples-minimal] - [examples-canadas][examples-canadas] - [examples-monorepo][examples-monorepo] - [examples-react][examples-react] - [examples-react-and-alias][examples-react-and-alias] - [examples-typescript][examples-typescript] - [examples-node][examples-node] - [examples-lint][examples-lint] - [examples-compat][examples-compat] 🚧 - [examples-tests][examples-tests] 🚧 - [examples-webworker][examples-webworker] 🚧 - [examples-code-splitting][examples-code-splitting] 🚧 - [examples-es6-ts-config][examples-es6-ts-config] 🚧 [example-minimal]: example-minimal [examples-compat]: https://github.com/fliphub/fliphub/tree/master/examples/compat [examples-react]: https://github.com/fliphub/fliphub/tree/master/examples/react [examples-react-and-alias]: https://github.com/fliphub/fliphub/tree/master/examples/react-and-alias [examples-canadas]: https://github.com/fliphub/fliphub/tree/master/examples/canadas [examples-lint]: https://github.com/fliphub/fliphub/tree/master/examples/lint [examples-empty]: https://github.com/fliphub/fliphub/tree/master/examples/empty [examples-monorepo]: https://github.com/fliphub/fliphub/tree/master/examples/monorepo [examples-typescript]: https://github.com/fliphub/fliphub/tree/master/examples/typescript [examples-webworker]: https://github.com/fliphub/fliphub/tree/master/examples/webworker [examples-tests]: https://github.com/fliphub/fliphub/tree/master/examples/tests [examples-code-splitting]: https://github.com/fliphub/fliphub/tree/master/examples/code-splitting [examples-es6-ts-config]: https://github.com/fliphub/fliphub/tree/master/examples/es6-ts-config [examples-node]: https://github.com/fliphub/fliphub/tree/master/examples/node # 🔌 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][flow-middleware] #### example ```js fliphub.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](#deep-debugging) 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][shrinkwrap] - [multiple react refs][react-refs-error] 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](#home) ### 🔗 resources - [🗼 babel aliases][babel-module-resolver] - [🕸 webpack aliases][webpack-alias] - [💣 fusebox aliases][fusebox-alias] - ✔️💣🕸 ## 🍰 presets ### add your own presets ```js .extendPresets({ 'inferno': { loaders: ['styleloader'], alias: ['moose', 'igloo', 'inferno'], html: '#root', }, }) ``` ### built in presets - [built in presets][src-presets] ## 🍦 default settings - [see the code][src-defaults] ### 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](#flags) are true, it would add the fusebox property to any app that has passed [filters](#filters) and is being built. ```js fliphub.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][todo-presets] ## params - converts shorthand code to webpack configs - [read the code][src-params] - ✔️💣🕸 ## 💣🛅 fusebox - converts webpack configs to fusebox configs - [read the code][src-fusebox-middleware] - ✔️💣 - [todo-build-systems][todo-build-systems] - needs to pass in more of the config ## ☺️️🛅 happypack - [happypack][happypack] - ✔️🕸 ### defaults ```js happypack: { cache: false, threads: 4, include: [ './', ], } ``` ```js { _noop: true, clean: false, // bool, or array<string> } ``` ## 🗺 sourcemaps - ✔️💣🕸 ### defaults ```js env: { development: { useSourceMaps: true, sourceMapTool: '#source-map', } production: { useSourceMaps: true, sourceMapTool: 'hidden', }, } ``` ## ⚖️ loaders - ✔️💣🕸 - .loaderOptions ### defaults ```js loaders: { 'babel': {}, 'json': {}, }, ``` ## 🚩 flags flags can be used to find global variables passed around for configuration from [globals][node-global] ### defaults ```js 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 ```js 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][yargs] - [node-flag][node-flag] - ✔️💣🕸 ### ⚠ - needs ungreedy search - [todo-flags][todo-flags] ## ♼ environment is an extension of [flags](#flags) as a middleware using flags ### defaults ```js env: { production: { uglify: true, defineProduction: true, run: false, compile: true, sourceMaps: false, sourceMapTool: 'hidden', }, development: { noEmitErrors: true, }, } ``` ## ☕🏳️ filters white [flags](#flags) are used to filter which apps are run for different [operations](#app-operations) apps, and app operations can be filtered based on flags either per app, or for all apps. [see the examples](#examples) ## configOut - writes the generated config to a file, for use with [babel-module-resolver][babel-module-resolver] - ✔️💣🕸 ## polyfills - can be used currently only for polyfilling window when you `.exec` in [app operations](#app-operations) ### ⚠ - ✔️🕸 - needs docs - [todo-polyfill][todo-polyfill] ## externals - allows you to exclude paths from a bundle - ✔️💣🕸 - [webpack externals][webpack-externals] - [fuse exclude][fuse-arithmetic] ## 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][todo-tests] # 👑⚔️ commander ### resources - [commanderjs][commanderjs] ### ⚠ - needs docs - needs lots of work - [todo-commander][todo-commander] # apps - multiple apps [flow-app][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][com-avoid-symlinks] and [massive package sizes][com-massive-package-sizes] ### ⚠ - needs docs # 🕳 digging deeper ## 🖇 helpers ## 🐛 deep-debugging inside of every workflow, there is [fliplog][fliplog-url] ### defaults ```js 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 [flipfile][flipfile-url] ## 🌐 port used for finding available ports if preferred ones are not available ## html ## example ```js { 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 ## 🏭 behind the scenes ## core ## middleware - flattening ## builders ## core ## 🖇 helpers reference & context ## 📅 plans - [board](https://github.com/fliphub/fliphub/issues#boards?repos=82865013) # 🏗 build systems / builders - [webpack][webpack-url] - [fusebox][fusebox-url] - [rollup][rollup-url] - [another bundler? request it][new-issue-url] [new-issue-url]: https://github.com/fliphub/fliplog/issues/new [fliplog-url]: https://www.npmjs.com/package/fliplog [flipfile-url]: https://www.npmjs.com/package/flipfile [src-pkg-json]: https://github.com/fliphub/fliphub/tree/master/package.json [src-params]: https://github.com/fliphub/fliphub/tree/master/src/middleware/defaults.js [src-fusebox-middleware]: https://github.com/fliphub/fliphub/tree/master/src/middleware/builders/fusebox.js [src-presets]: https://github.com/fliphub/fliphub/tree/master/src/middleware/presets.js [src-defaults]: https://github.com/fliphub/fliphub/tree/master/src/middleware/defaults.js [flow-middleware]: https://github.com/fliphub/fliphub/tree/master/flow/MiddlewareInterface [flow-app]: https://github.com/fliphub/fliphub/tree/master/flow/MiddlewareInterface [todo-flags]: https://github.com/fliphub/fliphub/tree/master/docs/todos/middleware/flags.md [todo-aliasing]: https://github.com/fliphub/fliphub/tree/master/docs/todos/middleware/aliasing.md [todo-compat]: https://github.com/fliphub/fliphub/tree/master/docs/todos/middleware/compat.md [todo-HMR]: https://github.com/fliphub/fliphub/tree/master/docs/todos/middleware/HMR.md [todo-loaders]: https://github.com/fliphub/fliphub/tree/master/docs/todos/middleware/loaders.md [todo-middleware]: https://github.com/fliphub/fliphub/tree/master/docs/todos/middleware/middleware.md [todo-polyfill]: https://github.com/fliphub/fliphub/tree/master/docs/todos/middleware/polyfill.md [todo-presets]: https://github.com/fliphub/fliphub/tree/master/docs/todos/middleware/presets.md [todo-tasks]: https://github.com/fliphub/fliphub/tree/master/docs/todos/middleware/tasks.md [todo-architecture]: https://github.com/fliphub/fliphub/tree/master/docs/todos/architecture.md [todo-build-systems]: https://github.com/fliphub/fliphub/tree/master/docs/todos/build-systems.md [todo-commander]: https://github.com/fliphub/fliphub/tree/master/docs/todos/commander.md [todo-core]: https://github.com/fliphub/fliphub/tree/master/docs/todos/core.md [todo-docs]: https://github.com/fliphub/fliphub/tree/master/docs/todos/docs.md [todo-examples]: https://github.com/fliphub/fliphub/tree/master/docs/todos/examples.md [todo-helpers]: https://github.com/fliphub/fliphub/tree/master/docs/todos/helpers.md [todo-later-soon-next]: https://github.com/fliphub/fliphub/tree/master/docs/todos/later-soon-next.md [todo-perf]: https://github.com/fliphub/fliphub/tree/master/docs/todos/perf.md [todo-tests]: https://github.com/fliphub/fliphub/tree/master/docs/todos/tests.md [npm-image]: https://img.shields.io/npm/v/fliphub.svg [npm-url]: https://npmjs.org/package/fliphub [david-deps-img]: https://david-dm.org/fliphub/fliphub.svg [david-deps-url]: https://david-dm.org/fliphub/fliphub [emoji-commits]: https://github.com/aretecode/emoji-commits/ [chalk]: https://github.com/chalk/chalk [react-refs-error]: https://facebook.github.io/react/docs/error-decoder.html?invariant=119 [shrinkwrap]: https://docs.npmjs.com/cli/shrinkwrap [babel-setup]: https://babeljs.io/docs/setup/ [babel-module-resolver]: https://github.com/tleunen/babel-plugin-module-resolver [babel-loader-builder]: https://github.com/aretecode/babel-loader-builder [babel-monorepo]: [https://github.com/babel/babel/blob/master/doc/design/monorepo.md] [babel-make]: [https://github.com/babel/babel/blob/master/Makefile] [webpack]: https://webpack.js.org/ [webpack-alias]: https://webpack.js.org/configuration/resolve/ [webpack-root]: https://webpack.js.org/guides/migrating/#resolve-root-resolve-fallback-resolve-modulesdirectories [medium-webpack-difficulty]: https://medium.com/@dtothefp/why-can-t-anyone-write-a-simple-webpack-tutorial-d0b075db35ed#.b57i57t24 [webpack-externals]: https://webpack.js.org/configuration/externals/#components/sidebar/sidebar.jsx [happypack]: https://github.com/amireh/happypack [webpack-plugin-uglify]: https://webpack.js.org/guides/migrating/#uglifyjsplugin-minimize-loaders [fusebox]: http://fuse-box.org/ [fusebox-alias]: http://fuse-box.org/#alias [fusebox-homedir]: http://fuse-box.org/#home-directory [fuse-arithmetic]: http://fuse-box.org/#arithmetic-instructions [sigh]: https://github.com/sighjs/sigh [fly]: https://github.com/flyjs/fly [brunch]: http://brunch.io/ [broccili]: [http://broccolijs.com/] [gearjs]: [http://gearjs.org/] [yeoman]: [http://yeoman.io/] [make]: [https://github.com/mklabs/make] [documentationjs]: [http://documentation.js.org/] [ninjabuild]: [https://ninja-build.org/manual.html] [meteor-scripts]: [https://github.com/meteor/meteor/tree/devel/scripts] [facebook-gulp]: [https://github.com/facebook/react/blob/master/gulpfile.js] [facebook-scripts]: [https://github.com/facebook/react/tree/master/scripts] [commanderjs]: https://github.com/tj/commander.js/ [node-global]: https://nodejs.org/api/globals.html [node-process-env]: https://nodejs.org/api/process.html#process_process_env [node-util-format]: https://nodejs.org/api/util.html#util_util_format_format [nodejs-tosource]: https://github.com/marcello3d/node-tosource [yargs]: https://www.npmjs.com/package/yargs [node-flag]: https://www.npmjs.com/package/node-flag [standard-image]: https://img.shields.io/badge/%F0%9F%91%95%20code%20style-standard%2Bes6+-blue.svg [standard-url]: https://github.com/aretecode/eslint-config-aretecode [license-image]: http://img.shields.io/badge/license-MIT-blue.svg?style=flat [license-url]: https://spdx.org/licenses/MIT [slack-url]: https://now-examples-slackin-mquyzyrecx.now.sh/ [slack-image]: https://now-examples-slackin-mquyzyrecx.now.sh/badge.svg [com-avoid-symlinks]: @TODO [com-massive-package-sizes]: @TODO [gitter-badge]: https://img.shields.io/gitter/room/fliphub/pink.svg [gitter-url]: https://gitter.im/fliphub/Lobby