Runtime environment

By default, Asciidoctor.js will try its best to automatically detect the runtime environment using Duck typing.

Configure the Runtime environment

The following section covers an advanced topic. For most use cases, you don’t need to explicitly configure the runtime environment.

Now that you have been warned, you can use the runtime configuration object when instantiating Asciidoctor.js to explicitly define the runtime environment:

const asciidoctor = require('asciidoctor')({
  runtime: {
    platform: 'browser',
    engine: 'v8',
    framework: 'webextensions'
  }
})

The following values are recognized:

runtime.platform
  • node: Node.js

  • java: Java (GraalVM)

  • standalone: Standalone (spidermonkey)

  • browser: Browser (Chrome, Firefox, Opera, Edge…​)

runtime.engine
runtime.framework

I/O module

The I/O module provides an implementation for reading files.

By default, Asciidoctor.js will determine the I/O module upon the runtime environment. To explicitly define the I/O module, you can specify the attribute runtime.ioModule when instantiating Asciidoctor.js:

const asciidoctor = require('asciidoctor')({
  runtime: {
    ioModule: 'xmlhttprequest'
  }
})

ioModule can be one of:

node

The implementation will use the fs module.

xmlhttprequest

The implementation will use the XMLHttpRequest object.

graalvm

The implementation will use a bounded class named IncludeResolver:

context.getPolyglotBindings().putMember("IncludeResolver", new IncludeResolver());
spidermonkey

The implementation will use the read function.

phantomjs

The implementation will use the fs.read function.

Retrieve the runtime environment

Once Asciidoctor.js is instantiated, you can retrieve the runtime environment with the getRuntime function:

const asciidoctor = require('asciidoctor')()
console.log(asciidoctor.getRuntime())
// { ioModule: 'node', platform: 'node', engine: 'v8', framework: '' }

It can be useful to make sure that the runtime environment has been correctly determined.