@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 programmatically¹ 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 start

To test the example:

Open https://localhost in 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

Keywords

hypha

web compiler

Bankai

FAQs

What is @hypha/web-compiler?

Is @hypha/web-compiler well maintained?

Package last updated on 03 Mar 2019

Did you know?

Socket for GitHub automatically highlights issues in each pull request and monitors the health of all your open source dependencies. Discover the contents of your packages and block harmful activity before you install or update your dependencies.

Install

@hypha/web-compiler