appstackr
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-dev
Edit 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 appstack
Run command
$ npm run bsync
Find 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/generator
create the app:
$ express /tmp/foo && cd /tmp/foo
Install dependencies:
$ npm install
Stack up front-end bundles:
$ npm run appstack
Start server & appwatch together
$ npm run bsync
Stack 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 appwatch
Usage
stacks.js setup
module.exports = [
{
name: 'site',
nature: 'js',
files: 'client/site/**/*.js'
},
{
...
}
];
stacks.js options
- name:
string
e.g. site or base/site - files:
glob pattern
, or path
resolved to a node module of array
, e.g. site/**/*.js
, react
, react/addons
- watch:
array
or string
, to watch the files not included in files
array. Useful for files required/imported
in js or css files. - nature:
js|jhtml|css|chtml|html
- commonjs:
true
, if nature is js|jhtml
and browserify options. commonjs is auto set to true
- 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
.jsx
file in a stack. - or require
.jsx
file 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 appbuild
Create 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:js
Benefits
-
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 of js|css
files will be changed. Thereafter, in your CDN
, these static files will
have different version 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 ANT
to 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 is less is more
, including no more verbose syntax in building script,
easy to tell where are the source files, and where are the destination files.