benpptungappstackr
A personal opinioned tool to strategically stack up front-end bundles from js, jsx, css, scss, less, stylus, html-styled template files( swig, ractive, mustache ), or pure html files. Using browserify, browser-sync, uglifyjs, auto-prefixer, htmlcompressor..etc.
Add hashes to the stacked bundles. So the browser can long-term cache js, image and css files. Speed up website in production environment.
Beware to use this tool. It is only working and tested on node.js 4.4.3, so there should be some problems if node.js > 4.4.3.
Todo list
- switch Gaze to chalk.
- multiple stack files to separate concerns
- update modules
- rewrite entirely to make it easy to maintain
Installation
Install to the project as local dependency
$ npm install appstackr --save-devEdit package.json script property as following( use express as example )
"scripts": {
"start" : "DEBUG=<app_name>:* node ./bin/www",
"appbuild": "appbuild",
"appstack": "appstack",
"appwatch": "appwatch --server 0.0.0.0:3000",
"bsync" : "npm start & npm run appwatch"
}Add a stacks.js file like following
module.exports = [
{
name: 'base/site',
nature: 'js',
files: 'path/to/client/**/*.js'
},
{
name: 'base/site',
nature: 'css',
files: [
'path/to/client/**/*.css',
'path/to/client/**/*.scss',
'path/to/client/**/*.less',
'path/to/client/**/*.styl'
]
}
];Stack up front-end bundles /js/base/site.min.js and /css/base/site.min.css
$ npm run appstackRun command
$ npm run bsyncFind the view files, edit the src and href pointed to /js/base/site.min.js and /css/base/site.min.css
Example:
https://github.com/benpptung/appstackr-examples
Generate an express project with appstackr installed
Make sure express-generator is not installed, or remove it temporally
Install the generator:
$ npm install -g benpptung/generatorcreate the app:
$ express /tmp/foo && cd /tmp/fooInstall dependencies:
$ npm installStack up front-end bundles:
$ npm run appstackStart server & appwatch together
$ npm run bsyncStack up bundles while starting appwatch
"appwatch": "appwatch -i --server 0.0.0.0:3000"Use browser-sync server ( No your own routes & views )
appstackr will direct browser-sync to watch public folder, which is defined in global config, or appstackr-settings.json
"appwach": "appwatch -b"
$ npm run appwatchUsage
stacks.js setup
module.exports = [
{
name: 'site',
nature: 'js',
files: 'client/site/**/*.js'
},
{
...
}
];stacks.js options
- name:
stringe.g. site or base/site - files:
glob pattern, orpathresolved to a node module ofarray, e.g.site/**/*.js,react,react/addons - watch:
arrayorstring, to watch the files not included infilesarray. Useful for filesrequired/importedin js or css files. - nature:
js|jhtml|css|chtml|html - commonjs:
true, if nature isjs|jhtmland browserify options. commonjs is auto set totrue - browserfiy: browserify() options. Three additonal options:
exposes,externals,ignores. - autoprefixer: auto-prefixer options to define which browsers want to support.
Example to bundle modules into stacks
module.exports = [
{
name: 'base/bundle',
nature: 'js',
files: 'superagent, insert-css',
browserify:{
exposes: '*' // Make all modules outside the bundle with require().
}
},
{
name: 'base/site',
nature: 'js',
files: [
'client/helper.js'
'node_modules/public-browserify/react.js'
],
browserify: {
exposes: [
'helper.js:helper',
'react.js:react'
]
// Make private module outside the bundle using <file_name>:<module_name> pattern
}
},
{
name: 'base/shim',
nature: 'js',
files: [
'node_modules/es5-shim/es5-shim.min.js',
'node_modules/es5-shim/es5-sham.min.js',
'node_modules/console-polyfill/index.js',
'node_modules/html5shiv/dist/html5shiv.min.js',
'node_modules/respond.js/dest/respond.matchmedia.addListener.min.js'
]
// concat plain js files
},
]browserify tranforms support
Require scss|less|styl|css file directly in js or jsx
var React = require('react');
var insCSS = require('insert-css');
insCSS(require('./assets/style.scss'));
module.exports = React.createClass(...);
react.js support
- Put
.jsxfile in a stack. - or require
.jsxfile in the codes.
auto-prefixer support
module.exports = [
{
"name": "bootstrap",
"nature": "css",
"files": [
"less/bootstrap/bootstrap.less"
],
"autoprefixer": "> 5%, IE 8"
},
]Default directory structure
|-- public ( hold the js/css/image files )
|
|-- views ( hold the view files for server routes )
|
|-- stacks.js ( how to stack up front-end bundles )
|
\-- appstackr-settings.json ( configure appstackr, e.g. define your own public js folder name )appbuild
$ npm run appbuildCreate dist folder, auto-refactor the views, public assests. Upload public assets to cdn server, and point views folder to dist/views in production environment.
Debug
appstackr has no source map. To figure out what's wrong, use the following command to beautify the codes and see where the error is in browser console. If not sure which source file it is, use stacks.js as an index. e.g. to check example.min.js
$ npm run appstack -- -bf example:jsBenefits
appstackr is designed as a local dependency in a project.That said, if you upgrade your global build tool, it's very possible your next building results ofjs|cssfiles will be changed. Thereafter, in yourCDN, these static files will have differentversion hash tags, then your customers are forced to reload the new static files, just because you upgrade your build tool.appstackr is not designed to be a public project or replace other tools. It's just a personal opinioned tool in my produciton environment,
continuely improvement is for sure.appstackr is an inspiration after couple years using
ANTto maintain my websites. It had been a nightmare, and I don't want it to happen again. One of the most important priority in appstackr isless is more, including no more verbose syntax in building script, easy to tell where are the source files, and where are the destination files.