search

choojs / bankai

:station: - friendly web compiler
Apache License 2.0
1.09k stars 102 forks source link
assets browserify compile css css-in-js modular server sheetify

readme

bankai

npm version build status downloads js-standard-style

The easiest way to compile JavaScript, HTML and CSS.

We want people to have fun building things for the web. There should be no hurdles between a great idea, and your first prototype. And once you're ready, it should be easy to package it up and share it online. That's Bankai: a tool that helps you build for the web. No configuration, and no hassle - that's our promise.

If this is your first time building something for the web, take a look at choojs/create-choo-app to help get a project setup from scratch :sparkles:.

Usage

  $ bankai <command> [entry] [options]

  Commands:

    build       compile all files to dist/
    inspect     inspect the bundle dependencies
    start       start a development server

  Options:

    -d, --debug       output lots of logs
    -h, --help        print usage
    -q, --quiet       don't output any logs
    -v, --version     print version

  Examples:

    Start a development server
    $ bankai start index.js

    Visualize all dependencies in your project
    $ bankai inspect index.js

    Compile all files in the project to disk
    $ bankai build index.js

  Running into trouble? Feel free to file an issue:
  https://github.com/choojs/bankai/issues/new

  Do you enjoy using this software? Become a backer:
  https://opencollective.com/choo

⚠️ HTTPS Instructions

When you first open up your application in a browser, you'll probably see a warning page about HTTPS connections being untrusted. No worries, this is entirely expected behavior. Follow the instructions below to solve this for your browser.

How does this work? For HTTPS to run on localhost, we must sign a TLS certificate locally. This is better known as a "self-signed certificate". Browsers actively check for certificates from uknown providers, and warn you (for good reason!) In our case, however, it's safe to ignore. HTTPS is needed for an increasing amount of APIs to work in the browser. For example if you want to test HTTP/2 connections or use parts of the storage API, you have no choice but to use an HTTPS connection on localhost. That's why we try and make this work as efficiently, and securely as possible. We generate a unique certificate for each Bankai installation. This means that you'll only need to trust an HTTPS certificate for Bankai once. This should be secure from remote attackers, because unless they have successfully acquired access to your machine's filesystem, they won't be able to replicate the certificate.
Firefox Instructions

Step 1

A wild security screen appears!. Click on "advanced". firefox01

Step 2

More details emerge! Click on "Add Exception". firefox02

Step 3

In the dropdown click "Confirm Security Exception". firefox03

Step 4

Success! firefox04
Chrome Instructions Click the "more details" dropdown, then click "proceed". Pull Request for screenshots welcome!
Safari Instructions

Step 1

A wild security screen appears! Click "Show Certificate". safari01

Step 2

More details emerge! Check "Always trust 'localhost'…". safari02

Step 3

The box is checked! Click "Continue". safari03

Step 4

A box is asking you for your crendentials. Fill them in, and hit "Enter".

Step 5

Success! safari04

Optimizations

Bankai applies lots of optimizations to projects. Generally you won't need to care how we do this: it's lots of glue code, and not necessarily pretty. But it can be useful to know which optimizations we apply. This is a list:

JavaScript

And bankai uses tinyify, which adds the following optimizations:

CSS

HTML

Configuration

The Bankai CLI doesn't take any flags, other than to manipulate how we log to the console. Configuring Bankai is done by modifying package.json.

Bankai is built on three technologies: browserify, sheetify, and documentify. Because these can be configured inside package.json it means that Bankai itself can be configured from there too. Also if people ever decide to switch from the command line to JavaScript, no extra configuration is needed.

{
  "name": "my-app",
  "browserify": {
     "transform": [
       "some-browserify-transform"
     ]
   },
   "sheetify": {
     "transform": [
       "some-sheetify-transform"
     ]
   },
   "documentify": {
     "transform": [
       "some-documentify-transform"
     ]
   }
}

Custom HTML

By default, Bankai starts with an empty HTML document, injecting the tags mentioned above. You can also create a custom template as index.html, and Bankai will inject tags into it instead.

If you export your Choo app instance after doing .mount(), Bankai respects the mount location during server side rendering:

// app.js
...
module.exports = app.mount('#app')
<!-- index.html -->
...
<body>
  <div id="app"></div>
  <div id="footer">© 2018</div>
</body>
...

Injecting headers - favicon.ico, CDNs, manifests etc...

You might be looking to use some of the fantastic third party libraries or tools out there. Take the font-awesome library for example, but there are plenty of others. To do so, you typically need to include additional css or js libraries in your <head>. And you can do this by setting up your documentify transform.

In this example, you will need to add a "documentify" transform which specifies a js file used, but you will also need a couple of extra npm libraries which you can install with:

npm i hstream dedent

Now in package.json, add the following transform:

"documentify": {
    "transform": [
      [
        "./lib/document.js",
        {
          "order": "end"
        }
      ]
    ]
  },

In this example, we are storing the transform in a folder called lib, which you will need to create, and create a document.js file in it. Edit the file called document.js and put the following transform code in it:

var dedent = require('dedent')
var hyperstream = require('hstream')

module.exports = document

function document () {
  return hyperstream({
    'meta[name="viewport"]': {
      content: 'width=device-width, initial-scale=1, viewport-fit=cover'
    },
    head: {
      _prependHtml: dedent`
      <link rel="manifest" href="https://github.com/choojs/bankai/blob/master/manifest.json">
      <link rel="stylesheet" href="https://cdnjs.cloudflare.com/ajax/libs/font-awesome/4.7.0/css/font-awesome.min.css">
      `,
      _appendHtml: dedent`
        <link rel="shortcut icon" href="https://github.com/choojs/bankai/blob/master/favicon.ico">
      `
    }
  })
}

This example now enables Bankai to generate an index.html file which has a link to the font-awesome css cdn, a manifest.json file, and a favicon.ico file ready for deployment.

Service Workers

Bankai comes with support for service workers. You can place a service worker entry point in a file called sw.js or service-worker.js. Bankai will output a browserify bundle by the same name.

You can easily register service workers using choo-service-worker:

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:

app.use(require('choo-service-worker')('/service-worker.js'))

Service workers have access to some environment variables:

HTTP

Bankai can be hooked up directly to an HTTP server, which is useful when working on full stack code.

var bankai = require('bankai/http')
var http = require('http')
var path = require('path')

var compiler = bankai(path.join(__dirname, 'client.js'))
var server = http.createServer(function (req, res) {
  compiler(req, res, function () {
    res.statusCode = 404
    res.end('not found')
  })
})

server.listen(8080, function () {
  console.log('listening on port 8080')
})

Babel

Not all browsers support all of the Web Platform's features. So in order to use newer features on older browsers, we have to find a solution. The best solution out there at the moment is 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 Bankai 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, Bankai 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).

require('babel-polyfill')

We don't include this file by default in Bankai, 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))

Whenever an internal error occurs.

compiler.on('change', callback(nodeName, edgeName, state))

Whenever a change in the internal graph occurs.

API

compiler = bankai(entry, [opts])

Create a new bankai instance. Takes a path to a JavaScript file as the first argument. The following options are available:

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.

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

Apache License 2.0