ArcheHTML

HTML renderer for vanilla microfrontends.

Source code: GitHub | License: CFOSS

Installation

with npm:

npm i arche-html

require ArcheHTML with Node.js CommonJS modules:

const ArcheHTML = require("arche-html")

import ArcheHTML with Node.js ECMAScript modules:

import ArcheHTML from "arche-html"

Usage

const ArcheHTML = require("arche-html")

const archeHtml = new ArcheHTML("/path/to/react/Root.js")

const html = await archeHtml.render("/", {
  global: {
    windowVarA: 1,
    windowVarB: "example",
    windowVarC: [1, 2, 3],
    windowVarD: { a: 1 },
  },
})

Docs

ArcheHTML

new ArcheHTML(rootImport string, {
  scriptImports: Array<string>,
}) -> ArcheHTML

ArcheHTML class. Creates an object that renders HTML from the root of an Arche client application. An Arche client application is a software application for the client that uses the Arche library.

Supported libraries with Arche:

• React
• Styled Components
• document

Arguments:

• rootImport - string - The file path to the root file of the Arche client application.
• options
  • scriptImports - Array<string> - An array of urls of scripts to import before the root import within a render of an Arche client application. Defaults to [].

const ArcheHTML = require("arche-html")

const archeHTML = new ArcheHTML("/path/to/react/Root.js", {
  scriptImports: [
    "/path/to/global.js",
  ],
})

render

render(url string) -> html Promise<string>

render(url string, options {
  global: Object<string|number|Array|Object>,
}) -> html Promise<string>

Renders the Arche client application at the url.

Arguments:

• url - string - The value of location.pathname that is available to the Arche client application for the render.
• options
  • global - Object<string|number|Array|Object> - Properties that are directly set on the window object of the Arche client application for the render.

Return:

• html - Promise<string> - The rendered HTML of the Arche client application.

Polyfills

ArcheHTML aliases globalThis as window to simulate a client environment, and provides polyfills of client global variables for the server as Arche, React, location, localStorage, matchMedia, and document.

To define custom polyfills of global variables for your Arche client application or other script imports, define polyfills in a script import of scriptImports. Because the script imports are imported in order, the polyfills script should be the first or one of the first script imports. Here is an example of a polyfills script:

// polyfills.mjs

import rubico from "rubico/dist/rubico.mjs"

window.rubico = rubico
window.BezierEasing = () => {}

Here is an example defining the polyfills script in scriptImports:

// server.js

const ArcheHTML = require("arche-html")

const archeHTML = new ArcheHTML("/path/to/react/Root.js", {
  scriptImports: [
    "/path/to/polyfills.mjs",
    "/path/to/global.js",
  ],
})

The polyfills in ArcheHTML are minimal and incomplete. If you have a need for a polyfill defined in ArcheHTML, please do not hesitate to contribute.

Contributing

To contribute, you can just open a pull request with a description of the changes.

License

ArcheHTML is distributed under the CFOSS License.

Support

• minimum Node.js version: 16

Supported Platforms

• Linux