Configuration
Applications that use jsii modules start a child node process that runs the jsii runtime (see
Runtime Architecture). The environment variables on this page change how that process is started and what it
reports. They are read from the environment of the application, and the child process inherits that environment.
These settings choose which programs run as part of your application, and with which options. Anyone who can set
them can run code as your application, so only set them from sources you trust, the same way you would treat PATH.
The package cache has its own settings, described in Package Cache.
JSII_NODE
The node executable used to run the jsii runtime. The default is node, looked up in PATH. Use this to select a
specific node installation without changing PATH. The node version must be supported by the jsii runtime (see
Prerequisites).
| Runtime | Behavior |
|---|---|
| Python | Run directly, without a shell. |
| .NET | Run directly, without a shell. |
| Java | Run directly. If the value contains whitespace, it is run through /bin/sh -c (%COMSPEC% on Windows). |
| Go | Run directly, without a shell. |
On Java and Go, JSII_NODE is ignored when JSII_RUNTIME is set.
JSII_RUNTIME
Replaces the jsii runtime bundled with the runtime library for your language. The default is the bundled version, and you should only need to change it when developing jsii itself. Its meaning differs between runtimes:
| Runtime | Value | Behavior |
|---|---|---|
| Python | Path to the runtime script | Run as JSII_NODE <options> JSII_RUNTIME, without a shell. |
| .NET | Path to the runtime script | Run as JSII_NODE <options> JSII_RUNTIME, without a shell. The path is not quoted, so it cannot contain spaces. |
| Java | Command line | Run directly. If the value contains whitespace, it is run through /bin/sh -c (%COMSPEC% on Windows). |
| Go | Command line | Always run through $SHELL -c (or /bin/sh -c; %ComSpec% /d /s /c on Windows). |
On Java and Go, the value replaces the whole command, including node. For example, to use a local build of the jsii
runtime:
# Python and .NET
export JSII_RUNTIME=/path/to/jsii/packages/@jsii/runtime/bin/jsii-runtime.js
# Java and Go
export JSII_RUNTIME="node /path/to/jsii/packages/@jsii/runtime/bin/jsii-runtime.js"
The program must implement the kernel API specification in a version compatible with the runtime library.
NODE_OPTIONS
Standard Node.js options, applied to the jsii runtime process.
For example, NODE_OPTIONS=--inspect-brk lets you attach a debugger to the jsii runtime.
Python and .NET pass a larger heap limit (--max-old-space-size) on the command line. Command line options take
precedence over NODE_OPTIONS, so on these runtimes a --max-old-space-size in NODE_OPTIONS has no effect. Go sets
the heap limit through NODE_OPTIONS instead, only when NODE_OPTIONS is not set. A NODE_OPTIONS value you set
replaces it completely, so include --max-old-space-size yourself if your application needs the larger heap. Java does
not change the heap limit.
Python bin scripts generated by jsii-pacmak run with NODE_OPTIONS set to the options of the jsii runtime process,
not to the value in your environment.
Warning
Some Node.js options run code, for example --require and --import. That code runs inside the jsii runtime with
the same access as your application.
JSII_DEBUG
Set to any non-empty value to have the jsii runtime write a trace of its activity to STDERR. The trace includes every
request and response exchanged with the runtime library, and is intended for troubleshooting jsii itself.
Any non-empty value turns on the trace, including 0 and false. To turn it off, unset the variable. On Java, 0 and
false do turn off the extra line in which the runtime library prints the command used to start the jsii runtime, but
they still turn on the trace in the jsii runtime itself.
Warning
The trace contains the values your application passes to jsii modules and receives from them. These may include
secrets, such as credentials read from configuration files. Do not turn on JSII_DEBUG where STDERR is collected
or shared, for example in CI logs, unless you have checked the values involved.