@forge/bundler

Forge bundler

The bundler package is responsible for compiling the user code, including dependencies (NPM packages), into files that get uploaded to AWS Lambda.

This is required for two reasons:

• Forge only runs JavaScript functions (on either sandbox or Node runtime), so TypeScript has to be compiled to JavaScript.
• All files that the user code imports need to be available when the Forge function runs.

The bundler is used:

• When deploying a Forge app (forge deploy)
• When running an app locally (forge tunnel)

Implementation

Bundler uses webpack to compile user code.

Every entry point from the manifest (referenced in modules.function.handler) and resource for Native UI is compiled into a single JavaScript file containing all of its dependencies.

Sandbox runtime

Some built-in Node modules and globals are not exposed in the sandbox JavaScript environment. Accessing those at runtime would throw an error.

Where possible, the unavailable modules and globals are replaced with compatible implementations using ProvidePlugin and alias. If there is no point in providing an implementation altogether (e.g. dns module), it is replaced with a stub showing an "unsupported" message.

Some NPM modules provide different implementations for "browser" and "node" environments, based on package-browser-field-spec. Even though Forge functions run in Node.js, our environment is more compatible with "browser" implementations. The sandbox Webpack configuration sets the resolve options to prefer those.

Node runtime

The interface for the Forge functions is different from the XIS interface, see Node runtime: Technical Details. Therefore, a layer of wrapper code is required to convert the calls and responses.

To maintain the correspondence between AWS Lambda handler and the handler in the Forge manifest, the bundled user code is put into a new location, with the wrapper code left in the original place. For example, if the manifest specifies index.run as the handler, AWS Lambda function will have:

• index.js - wrapper code
• bundled/index.js - bundled user code from src/index.js

The wrapper code, when invoked:

• Parses the invocation request from XIS
• Sets up the environment (e.g. user variables) for the Forge function run
• Loads the user code
• Invokes the user code
• Converts the result or error to the XIS response format and returns it

The wrapper cannot load the user code before the environment is set up, as any actions that the user code does upon initialization might fail (e.g. because the proxy token is not yet set up).

However, wrapper needs to know which exports to make available. This information is passed to the bundler from the manifest: if it contains index.run and index.another as handlers, then the wrapper for index.js will need to export run and another. Bundler uses BannerPlugin to add this as a constant to each wrapper.

To redirect console calls from the user code to Xen Logs Ingestor that backs forge logs and the Forge Developer console, occurrences console are replaced with a custom implementation via ProvidePlugin.

Native UI

TODO: Not documented