Skip to content

GitLab

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

Update change log, bump minor version

parent be85b126
Hide whitespace changes
Inline Side-by-side
CHANGELOG.md
View file @ dc2ed35f
......@@ -10,6 +10,18 @@ The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.0.0/),
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](https://github.com/choojs/bankai)). This is a simplified version of Bankai, tuned specifically for the needs of the Hypha project.
......
README.md
View file @ dc2ed35f
......@@ -6,7 +6,7 @@
If you want a general purpose web compiler, please use Bankai and [back their project](https://opencollective.com/choo).
@hypha/web-compiler is a simplified version of Bankai, tuned for the needs of the Hypha project that uses [https-server](https://source.ind.ie/hypha/tools/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](https://source.ind.ie/hypha/tools/web-compiler/blob/master/CHANGELOG.md#100-2019-03-03).
## 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:
```sh
web-compiler inspect
```
## Example
@hypha/web-compiler is used by hooking it up to an HTTPS server like [@hypha/https-server](https://source.ind.ie/hypha/tools/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
browser.
- __[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
`bundle.js`.
- __[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`](https://devdocs.io/html/attributes#defer-attribute) attribute.
- __async load styles:__ loads styles in the background using the
[`preload`](https://devdocs.io/html/attributes#preload-attribute) attribute.
- __async load styles:__ preloads fonts in the background using the
[`preload`](https://devdocs.io/html/attributes#preload-attribute) 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
`manifest.json`.
- __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:
```js
// app.js
...
module.exports = app.mount('#app')
```
```html
<!-- index.html -->
...
<body>
<div id="app"></div>
<div id="footer">© 2018</div>
</body>
...
```
### 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](https://github.com/choojs/choo-service-worker):
```js
app.use(require('choo-service-worker')())
```
choo-service-worker defaults to `/sw.js` for the service worker file name. If
you named your service worker `service-worker.js` instead, do:
```js
app.use(require('choo-service-worker')('/service-worker.js'))
```
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
file.
* __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](https://babeljs.io/) 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`](https://github.com/ai/browserslist) 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`).
```js
require('babel-polyfill')
```
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](https://source.ind.ie/hypha/tools/web-compiler/blob/6e7b439ee7f3840b4ee275bf0a8787d2fbcf2482/README.md).
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.
- __opts.watch:__ 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](https://www.apache.org/licenses/GPL-compatibility.html).
[babelify]: https://github.com/babel/babelify
[brfs]: https://github.com/browserify/brfs
[browser-pack-flat]: https://github.com/goto-bus-stop/browser-pack-flat
[browserify]: https://github.com/browserify/browserify
[bundle-collapser]: https://github.com/substack/bundle-collapser
[clean-css]: https://github.com/jakubpawlowicz/clean-css
[common-shakeify]: https://github.com/browserify/common-shakeify
[documentify]: https://github.com/stackhtml/documentify
[envify]: https://github.com/hughsk/envify
[glslify]: https://github.com/glslify/glslify
[inline-critical-css]: https://github.com/stackcss/inline-critical-css
[nanohtml]: https://github.com/choojs/nanohtml
[purify-css]: https://github.com/purifycss/purifycss
[sheetify]: https://github.com/stackcss/sheetify
[split-require]: https://github.com/goto-bus-stop/split-require
[tinyify]: https://github.com/browserify/tinyify
[uglifyify]: https://github.com/hughsk/uglifyify
[unassertify]: https://github.com/unassert-js/unassertify
---
## 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:
```sh
web-compiler inspect
```
\ No newline at end of file
package.json
View file @ dc2ed35f
{
"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": "https://source.ind.ie/hypha/tools/web-compiler",
......
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

Like this? Fund us! Your patronage helps keep us independent and going.