Natural Performance Manager

    @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

    Install

    npm i @hypha/web-compiler

    DownloadsWeekly Downloads

    7

    Version

    1.1.0

    License

    AGPL-3.0-or-later

    Unpacked Size

    674 kB

    Total Files

    76

    Last publish

    Collaborators

    • aral