Verified Commit dc2ed35f authored by Aral Balkan's avatar Aral Balkan
Browse files

Update change log, bump minor version

parent be85b126
......@@ -10,6 +10,18 @@ The format is based on [Keep a Changelog](,
Nothing yet.
## [1.1.0] - 2019-03-03
### Changed
- Simplified the readme.
## [1.0.1] - 2019-03-03
### Fixed
- Updated the example in the readme.
## [1.0.0] - 2019-03-03
Initial release (forked from [Bankai]( This is a simplified version of Bankai, tuned specifically for the needs of the Hypha project.
......@@ -6,7 +6,7 @@
If you want a general purpose web compiler, please use Bankai and [back their project](
@hypha/web-compiler is a simplified version of Bankai, tuned for the needs of the Hypha project that uses [https-server]( for seamless installation and use of locally-trusted certificates during development (and, soon, seamless Let’s Encrypt certificate provisioning and use in production).
@hypha/web-compiler is a simplified version of Bankai, tuned specifically for the needs of the Hypha project. For a summary of the differences, [please see the change log](
## Installation
......@@ -16,19 +16,11 @@ npm i @hypha/web-compiler
## Usage
The primary use case of web-compiler is programmatically with Hypha.
In Hypha, web-compiler is used:
@hypha/web-compiler is used programmatically<sup>[1](#footnote1)</sup> within Hypha:
1. As a live build and reload tool on development.
2. As a build and optimisation tool on production.
There is a command-line binary but it is not used in Hypha except for its _inspect_ command:
web-compiler inspect
## Example
@hypha/web-compiler is used by hooking it up to an HTTPS server like [@hypha/https-server](
......@@ -140,193 +132,10 @@ server.listen(443, () => {
## Reference, other details, etc.
## Optimisations
The following optimisations are applied during a build:
### JavaScript
- __[nanohtml][]:__ Optimize `choo` HTML code so it runs significantly faster in the
- __[glslify][]:__ Adds a module system to GLSL shaders.
- __[brfs][]:__ Statically inline calls to `fs.readFile()`. Useful to ship assets
in the browser.
- __[envify][]:__ Allow environment variables to be used in the bundle. Especially
useful in combination with minification, which removes unused code paths.
- __[split-require][]:__ Lazy load parts of your application using the
[`require('split-require')`][split-require] function.
- __[babelify][]:__ Bring the latest browser features to _all_ browsers. See
[our babel section](#babel) for more details.
It also uses [tinyify][], which adds the following optimisations:
- __[browser-pack-flat][]:__ Remove function wrappers from the bundle, making
the result faster to run and easier to minify.
- __[bundle-collapser][]:__ Remove all pathnames from inside the bundle, and
replace them with IDs. This not only makes bundles smaller, it prevents
details from your local dev setup leaking.
- __[common-shakeify][]:__ Remove unused JavaScript code from the bundle. Best
known as _dead code elimination_ or _tree shaking_.
- __[unassertify][]:__ Remove all `require('assert')` statements from the code.
Only applied for production builds.
- __[uglifyify][]:__ Minify the bundle.
### CSS
- __[sheetify][]:__ extract all inline CSS from JavaScript, and include it in
- __[purifyCSS][purify-css]:__ removes unused CSS from the project.
- __[cleanCSS][clean-css]:__ minify the bundle.
### HTML
- __[inline-critical-css][]:__ extract all critical CSS for a page into the
`<head>` of the document. This means that every page will be able to render
after the first roundtrip, which makes for super snappy pages.
- __async load scripts:__ loads scripts in the background using the
[`defer`]( attribute.
- __async load styles:__ loads styles in the background using the
[`preload`]( attribute.
- __async load styles:__ preloads fonts in the background using the
[`preload`]( attribute.
- __server render:__ server renders Choo applications. We're welcome to
supporting other frameworks too. PRs welcome!
- __manifest:__ includes a link to `manifest.json` so the application can be
installed on mobile.
- __viewport:__ defines the right viewport dimensions to make applications
accessible for everyone.
- __theme color:__ sets the theme color defined in `manifest.json` so the
navigator bar on mobile is styled on brand.
- __title:__ sets the right title on a page. Either extracts it from the
application (choo only, for now) or uses whatever the title is in
- __live reload:__ during development, we inject a live reload script.
### Custom HTML
By default, @hypha/web-compiler starts with an empty HTML document, injecting the tags
mentioned [above](#html). You can also create a custom template as `index.html`,
and @hypha/web-compiler will inject tags into it instead.
If you export your Choo app instance after doing `.mount()`, @hypha/web-compiler respects the
mount location during server side rendering:
// app.js
module.exports = app.mount('#app')
<!-- index.html -->
<div id="app"></div>
<div id="footer">© 2018</div>
### Service Workers
@hypha/web-compiler comes with support for service workers. You can place a service worker
entry point in a file called `sw.js` or `service-worker.js`. @hypha/web-compiler will output
a browserify bundle by the same name.
You can easily register service workers using
choo-service-worker defaults to `/sw.js` for the service worker file name. If
you named your service worker `service-worker.js` instead, do:
Service workers have access to some environment variables:
* __process.env.STYLE_LIST:__ An array of URLs to stylesheet files.
* __process.env.SCRIPT_LIST:__ An array of URLs to script files.
* __process.env.ASSET_LIST:__ An array of URLs to assets.
* __process.env.DOCUMENT_LIST:__ An array of URLs to server-rendered routes.
* __process.env.MANIFEST_LIST:__ An array containing the URL to the manifest
* __process.env.FILE_LIST:__ An array of URLs to assets and routes. This can
be used to add all your app's files to a service worker cache.
## Babel
[Babel]( is a plugin-based JavaScript compiler. It takes
JavaScript in, and outputs JavaScript based for the platforms you've decided to
target. In @hypha/web-compiler we target the last 2 versions of FireFox, Chrome and Edge,
and every other browser that's used by more than 1% of people on earth. This
includes IE11. And if you have different opinions on which browsers to use,
@hypha/web-compiler respects `.babelrc` and [`.browserslistrc`]( files.
Some newer JavaScript features require loading an extra library; `async/await`
being the clearest example. To enable such features, the `babel-polyfill`
library needs to be included in your application's root (e.g. `index.js`).
We don't include this file by default because it has a significant
size overhead. Once Babel includes only the language features you're using,
we'll work to include `babel-polyfill` by default.
## Events
### `compiler.on('error', callback(nodeName, edgeName, error))`
For further information, [please see the pre-fork Bankai documentation](
Whenever an internal error occurs.
### `compiler.on('change', callback(nodeName, edgeName, state))`
Whenever a change in the internal graph occurs.
## API
### `compiler = webCompiler(entry, [opts])`
Create a new @hypha/web-compiler instance. Takes a path to a JavaScript file as the first argument. The following options are available:
- __opts.quiet:__ Defaults to `false`. Don't output any data to `stdout`. Useful
if you have your own logging system.
- Defaults to `true`. Watch for changes in the source files and
rebuild. Set to `false` to get optimized bundles.
- __babelifyDeps:__ Defaults to true. Transform dependencies with babelify.
### `compiler.documents(routename, [opts], done(err, { buffer, hash }))`
Output an HTML bundle for a route. Routes are determined based on the project's
router. Pass `'/'` to get the default route.
- __opts.state:__ Will be passed the render function for the route, and inlined
in the `<head>` of the body as `window.initialState`.
### `compiler.scripts(filename, done(err, { buffer, hash }))`
Pass in a filename and output a JS bundle.
### `compiler.assets(assetName, done(err, { buffer, hash }))`
Output any other file besides JS, CSS or HTML.
### `compiler.styles(name, done(err, { buffer, hash }))`
Output a CSS bundle.
### `compiler.manifest(done(err, { buffer, hash }))`
Output a `manifest.json`.
### `compiler.serviceWorker(done(err, { buffer, hash }))`
Output a service worker.
### `compiler.close()`
Close all file watchers.
## License
......@@ -335,22 +144,12 @@ Close all file watchers.
For license compatibility information, see [GPL-compatibility](
## Footnotes
<a name='footnote1'>1</a>: There is a command-line binary but, while it is functional, it is not used in Hypha except to gaze upon the beautiful output of the _inspect_ command, which visualises project/component sizes in the browser:
web-compiler inspect
\ No newline at end of file
"name": "@hypha/web-compiler",
"version": "1.0.1",
"version": "1.1.0",
"description": "A web compiler forked from Bankai and tuned for Hypha.",
"license": "AGPL-3.0-or-later",
"repository": "",
Markdown is supported
0% or .
You are about to add 0 people to the discussion. Proceed with caution.
Finish editing this message first!
Please register or to comment