tension
v0.0.6
Published
Universal application toolchain
Downloads
3
Readme
tension
Universal application toolchain
Motivation
Universal Javascript allows execution of a same code both on the client and the server. This approach saves development time dedicated to write application code capable of being rendered on client and server side.
On other hand, a lot of time is wasted to set up scripts/codes dedicated to manage the development process: call them the toolchain. Once done, it's difficult to adjust project structure without breaking the toolchain. It's even harder to maintain the same toolchain trough several projects.
The main purpose of tension is to provide a super interface on top of webpack2 to handle recurrent base configurations in universal applications.
Architecture
The architecture is originally based on the great react-universally's toolchain which offer a single run process to manage multiple bundle's hot development.
tension is a generic version of that toolchain with the minimum configurations for any web or node bundles. We tried to make its fingerprint as small as possible.
It work with a metafile - named tension.js by default - present in project root (beside the package.json). That metafile defines how webpack should create bundles from the source code.
A metafile must return a plain object where each key is a bundle declaration. Each bundle must specify at least the target type, the source path with the entry point and the output path (and the public path for the web target). Check the Metafile section to learn more about its structure.
A meta is intended to be read by the tension CLI. The CLI offer two main commands: one to start a hot development environment and another to make a build for production environment.
Installation
npm install tension --save-devGetting started
Requirements
- node@^6.6.0
- npm@^3.10.0
mkdir myapp
cd myapp
npm init
npm install tension --save-devClient bundle
We will start to discover how tension work by creating a client bundle. We will write its code into ./src/client and call its entry point index.js.
// mkdir -p ./src/client
// nano ./src/client/index.js
var MSG = 'Hello, world'
var main = () => document.getElementById('app').innerHTML = MSG
main()Now we will create the tension.js metafile at our project root level and declare our client bundle.
// nano ./tension.js
module.exports = {
client: {
// our bundle target
target: 'web',
// our bundle source path
srcPath: './src/client',
// our client entry point (relative to the source path)
entryIndex: 'index.js',
// our public path used to serve our bundle
publicPath: '/client/',
// our bundle build path
outputPath: './build/client'
}
}Okay let's launch a dev server to test our client bundle. We use the command dev provided by the tension CLI. The command dev takes the key which identify bundle metadata in the tension.js.
./node_modules/.bin/tension dev client
INFO metafile found: /home/steven/code/myapp/tension.js
INFO client Building bundle...
INFO client Build finished successfully
INFO client Hash: 0e6248de46f0cca1cd4d
...
INFO client ✓ Dev server is running at http://localhost:7331/client/
INFO ✓ Dev mode startedWe can access to our client bundle at http://localhost:7331/client/index.js.
Well. It's better if we can test it in a web page. Let's do it. We use the staticPath which its content will be served as static files by the dev server.
mkdir ./public
echo '<html>
<body>
<div id="app"></div>
<script src="/client/index.js"></script>
</body>
</html>' > ./public/index.html
# add staticPath in tension.js
nano ./tension.js
// client: {
// ...
// outputPath: './build/client',
// staticPath: './public'
// }
# launch the dev server
./node_modules/.bin/tension dev clientOpen your browser to check if our fantastic script works: http://localhost:7331/client/.
We can see "Hello, world".
Now we will test the hot reloading feature. Open our client entry point (./src/client/index.js) and add the following lines:
if (module.hot) {
module.hot.accept(main)
}Let's refresh the page under the browser. Now re-open our client entry point and change the var MSG value. Save the modification: that change is hot reloaded in the browser!
Under the hood, the dev server is provided by the great webpack-dev-server. In the metafile, the property devServer, under a web bundle, will be passed to the dev server API. So you can configure the dev server options as has describe in its documentation.
So if we want to use port 1337 for our dev server and disable hot reloading:
// nano ./tension.js
module.exports = {
client: {
target: 'web',
// ...
devServer: {
port: 1337,
hot: false
}
}
}### Server bundle
TODO
CLI
TODO
tension - Universal application toolchain
Usage
tension <command> [options] [flags]
Commands
analyze Analyze build
build Build application
clean Clean build
dev Starts application in dev mode
start Starts application
Options
-e, --env Environment name (defaults to "development")
-m, --meta Metafile path
-r, --root, Root path (defaults to the curent working directory)
Flags
--no-colors Disable colored output
-d, --debug Enable debug output
-v, --verbose Enable verbose output
Specials
-h, --help Show usage information (this message)
-V, --version Show current version (0.0.1)Metafile
TODO
License
MIT