@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-compilerUsage
@hypha/web-compiler is used programmatically1 within Hypha:
- As a live build and reload tool on development.
- 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 startTo test the example:
- Open
https://localhostin a browser to see the client-side routes (a Choo app). - Open the JavaScript console (and look in the server output in Terminal) and see the WebSocket message successfully echoed.
- 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