wcmp v1.1.1

A tiny 'web-compiler' for compiling sass and babel files, without the hassles of opinionated frameworks. It's a package that aims on writing vanilla apps with the cool features of now. Conveniant for when you wish not to use Webpack or some other over-complicated hard-to-come-by framework. It's just a bare minimum Node.js setup for creating websites and apps from scratch. Great starting point, super-extensible!

Installation

Clone the repository and install dependencies from npm:

$ git clone git@github.com:automagisch/wcmp.git
$ cd wcmp && npm install

Usage

All functionality is bundled inside package.json, and the scripts are aliased to their hooks in the tooling system:

npm: $ npm start
node: $ babel-node index.js
Starts the SCSS and Babel watchers. Use this command if you tend to construct UI's.

npm: $ npm run dev
node: $ nodemon --delay 2 --exec babel-node index.js --development --force-babel
Same as npm start, but it also uses nodemon to listen for file changes in /tooling and restart Node scripts on change. Use this mode if you intend to add functionality to WCMP.

npm: $ npm run html
node: $ babel-node index.js --html
Compile mustache files to html in /dist directory.

npm: $ npm run styles
node: $ babel-node index.js --styles
Compile sass files to css in /dist directory.

npm: $ npm run scripts
node: $ babel-node index.js --scripts
Compile babel files once to /dist directory.

npm: $ npm run build
node: $ babel-node index.js --build
Compile both babel, sass and html sources once to the /dist directory.

npm: $ npm test
node: $ node tests
Run all the tests located in the tests folder (see tests/include-as-module.js for a test example - you're also free in how you like to test, be creative - be logical!). like that how you could set up a simple test.)

npm: $ npm run compile
node: $ rm -rf tooling/build && babel tooling --out-dir tooling/build
The compile command will render ES-compliant code from the babel output. Use this if you want to run the code in production (tbh: can't imagine why at the time, but hey - it might be a usecase for somebody eventually)

Recommended is to use the npm aliases rather than calling babel-node straight from the cli.

Development

Since the setup is super-minimalistic, there is no convention, no guideline and most certainly no rules where you have to rely on. There is no exposed tech that need to be used, it is really just a bare sass/babel compiler.

HTML files can go directly in the root of the /dist folder. There is no server implementation in this package, but if you would like to serve the HTML with node.js, the structure of the app is perfect to implement it yourself. The Node.js code lives in the /tooling folder. Otherwise, it's entirely safe to just preview the html in your browser. Good luck!

A practical tip for making a node-server to host the dist folder:
If you like to serve your files over http for previewing, it's probably the best idea to create a new class for an express server in /tooling/lib and do all your server stuff there (keep it abstract and modular for the best experience). If you want to add configuration to this feature, you may want to create some default slots in ./tooling/settings.js and then configure them in the config.json file. The config.json file is always populated against the default settings object, so it's a very wise idea to implement this for any feature you like to see configured. It will prevent things from breaking, probably.

Configuration

All configurables are clustered in a file in the root called config.json. Babel and Sass settings can be implemented here. Upon start, this file is extended upon a default set of settings defined in index.js, and from that point passed around to every module. If you tend to extend the compilers functionality, make sure to also include some configurables in this JSON format.

Testing

From the same though the WCMP project has been built, so works testing. Tests are located in /tests and are powered by the index.js file in that folder. There are no testing frameworks involved so you are (like the rest of the app) entirely up to yourself to do that - the more vanilla, the better! Tests can be ran using npm test.

Sidenotes to maybe confuse you less

• .babelrc in the root accepts settings for the babel-node environment. The settings for the client babel can go in the babel section in config.json.
• nodemon.json accepts the settings and configuration for the dev-mode nodemon instance. This configuration is used when npm run dev is called.
• In theory it should be possible to have one WCMP on many projects, and use WCMP as the go-to compiler for any project. This will prove itself in a future release.
• To run this package correctly, babel-node is used. Babel-node is a package from the Babel guys that is practically a node.js environment for babel (node.js does not yet fully support all es6 features, so by the time of writing babel-node is the go-to solution). In the case this code has to be run on a legacy node.js system, configure .babelrc and compile the tooling folder with babel to es5-compliant JS (what babel does, actually - uhuh) to run safely in all node.js environments. However, in most cases this will not be of use.

Useful resources

Stuck in the stack? Time to take a dive in these resources for some troubleshooting:

• Node.js => Offical Node.js site/docs
• Babel => Official Babel site/docs
• Sass => Official Sass site/docs
• Mustache => Official Mustache site/docs
• Nodemon => Official Nodemon website

Issues

See 'issues' button on the top of the page.

Authors

Koen Houtman (Automagisch) - Creative Director at Cuckoo Sandbox / Front-end engineer and UX enthousiast

License

This package is MIT licensed. For more details see the LICENSE file.