@hypha/web-compiler

1.1.0 • Public • Published

@hypha/web-compiler

@hypha/web-compiler v1.0.0 was forked from Bankai v9.15.0.

Bankai is an excellent “friendly web compiler” by Yoshua Wuyts, Renée Kooi, and other contributors.

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 specifically for the needs of the Hypha project. For a summary of the differences, please see the change log.

Installation

npm i @hypha/web-compiler

Usage

@hypha/web-compiler is used programmatically1 within Hypha:

  1. As a live build and reload tool on development.
  2. As a build and optimisation tool on production.

Example

@hypha/web-compiler is used by hooking it up to an HTTPS server like @hypha/https-server.

The following example, taken from the initial scaffolding of Hypha, demonstrates how you can use @hypha/web-compiler in both development and production and alongside regular HTTPS and WebSocket routes (the latter demonstrated using the Express framework). As web-compiler uses server-sent events (SSE) for live reload, live reload will also work properly alongside your WebSocket routes.

To run the example:

You can checkout and run the initial Hypha scaffolding using the following commands:

git clone --branch 1.0.0 --single-branch https://source.ind.ie/hypha/hypha/
cd hypha
npm i && npm start

To test the example:

  1. Open https://localhost in a browser to see the client-side routes (a Choo app).
  2. Open the JavaScript console (and look in the server output in Terminal) and see the WebSocket message successfully echoed.
  3. Open https://locahost/https-get/ in a browser to hit the HTTPS GET route.

Code

Here is a simplified listing of the code from the Hypha scaffolding that you can use by adding whatever you like to client/index.js:

const httpsServer = require('@ind.ie/https-server')

const express = require('express')
const expressWebSocket = require('express-ws')

const path = require('path')

// Catch any uncaught errors.
process.on('uncaughtException', function (error) {
  console.log('Uncaught exception:', error)
})

// Create the Express app, the HTTPS server, and add WebSocket support.
const app = express()
const server = httpsServer.createServer({}, app)
expressWebSocket(app, server, { perMessageDeflate: false })

//
// Websocket routes go here.
//

app.ws('/echo', (webSocket, request) => {
  webSocket.on('message', message => {
    console.log('Got web socket request to echo ', message)
    webSocket.send(message)
  })
})

//
// Regular HTTPS routes go here.
//

app.get('/https-get', (request, response) => {
  response.writeHeader(200, {'Content-Type': 'text/html'})
  response.end('<!doctype html><html lang=\'en\'><head><meta charset=\'utf-8\'/><title>Hello</title><style>body{background-color: white; font-family: sans-serif;}</style></head><body><h1>Hypha</h1><p>Hello, I am a dynamically-served HTTPS GET route.</p></body></html>')
})

//
// Set up @hypha/web-compiler.
//
// In development, we use it as middleware to enable live compilation and live reload.
// In production, use build a static distribution and serve it with express.static.
//

// client/index.js is the entry-point of your client-side JavaScript (e.g., a Choo app).
const entryPoint = path.join(__dirname, 'client/index.js')

if (process.env.NODE_ENV === 'production') {
  // Build the static distribution and serve it in production.
  const build = require('@hypha/web-compiler/lib/cmd-build')
  build(entryPoint, null, {base: 'https://localhost'})
  app.use(express.static('client/dist'))
} else {
  // Set up development mode with live compilation and reload.
  const webCompilerMiddleware = require('@hypha/web-compiler/http')(entryPoint)
  app.use(webCompilerMiddleware)

  webCompilerMiddleware.compiler.on('error', (nodeName, edgeName, error) => {
    console.log(' ⚙ [web-compiler] Error:', nodeName, edgeName, error)
  })

  webCompilerMiddleware.compiler.on('change', function (nodeName, edgeName, nodeState) {
    const name = nodeName + ':' + edgeName
    console.log(' ⚙ [web-compiler]', name)
  })

  webCompilerMiddleware.compiler.on('ssr', function (result) {
    console.log(' ⚙ [web compiler] SSR:', result.success ? 'success' : 'fail')
  })
}

// Handle server errors.
app.use(function(error, request, response, next) {
  console.log('Server Error', error)
  response.send(500)
})

// Start the server.
server.listen(443, () => {
  console.log('Server running on port 443.\n')
})

Reference, other details, etc.

For further information, please see the pre-fork Bankai documentation.

License

  • Any code added starting from and including commit 7ae96cf36c3d335ef482a5e08c59d3b956d7a7b4 is released under AGPLv3 or later.
  • All code up to and including commit 41a32b3361d5ad926a74bf63fb5345606091a4fd is licensed under Apache License 2.0.

For license compatibility information, see GPL-compatibility.


Footnotes

1: 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

Package Sidebar

Install

npm i @hypha/web-compiler

Weekly Downloads

6

Version

1.1.0

License

AGPL-3.0-or-later

Unpacked Size

674 kB

Total Files

76

Last publish

Collaborators

  • aral