# @forge/bundler

> Default bundler for Forge apps

Latest version **7.3.2** (published 2026-11-09) · SEE LICENSE IN LICENSE.txt license · 0 weekly downloads

## Install

```sh
npm install @forge/bundler
pnpm add @forge/bundler
yarn add @forge/bundler
bun add @forge/bundler
```

## Health

**Score 60/100 (C)** — status: active.

Positive: has types; no vulnerabilities; recently updated; high maintenance score.

Warnings: low downloads; no esm support.

## Facts

| | |
|---|---|
| Version | 7.3.2 |
| Published | 2026-11-09 |
| First published | 2019-11-22 |
| Weekly downloads | 0 |
| License | SEE LICENSE IN LICENSE.txt |
| TypeScript types | bundled |
| Module format | CommonJS |
| Node | >=12.13.1 |
| Dependencies | 25 |
| Unpacked size | 426.3 KB |
| Known vulnerabilities | 0 |
| Install scripts | no |
| Author | Atlassian |
| Maintainers | atlassianartifactteam |

## Links

- npm: https://www.npmjs.com/package/@forge/bundler
- npm.io page: https://npm.io/package/@forge/bundler

## Dependencies (25)

- [tmp](https://npm.io/package/tmp.md) ^0.2.3
- [nock](https://npm.io/package/nock.md) 13.5.6
- [cheerio](https://npm.io/package/cheerio.md) ^1.2.0
- [webpack](https://npm.io/package/webpack.md) 5.109.2
- [chokidar](https://npm.io/package/chokidar.md) ^4.0.3
- [debounce](https://npm.io/package/debounce.md) ^2.2.0
- [ts-loader](https://npm.io/package/ts-loader.md) ^9.5.2
- [type-fest](https://npm.io/package/type-fest.md) 4.10.2
- [typescript](https://npm.io/package/typescript.md) 5.9.2
- [@babel/core](https://npm.io/package/@babel/core.md) ^7.29.7
- [@forge/i18n](https://npm.io/package/@forge/i18n.md) 1.0.1
- [@forge/lint](https://npm.io/package/@forge/lint.md) 6.4.0
- [@babel/types](https://npm.io/package/@babel/types.md) ^7.29.8
- [babel-loader](https://npm.io/package/babel-loader.md) ^8.3.0
- [@babel/parser](https://npm.io/package/@babel/parser.md) 7.29.9
- [@babel/traverse](https://npm.io/package/@babel/traverse.md) ^7.29.8
- [@forge/manifest](https://npm.io/package/@forge/manifest.md) 13.9.0
- [@forge/cli-shared](https://npm.io/package/@forge/cli-shared.md) 9.10.0
- [html-webpack-plugin](https://npm.io/package/html-webpack-plugin.md) ^5.6.3
- [webpack-bundle-analyzer](https://npm.io/package/webpack-bundle-analyzer.md) ^4.10.2
- [@babel/plugin-transform-react-jsx](https://npm.io/package/@babel/plugin-transform-react-jsx.md) ^7.29.7
- [@babel/plugin-transform-class-properties](https://npm.io/package/@babel/plugin-transform-class-properties.md) ^7.29.7
- [@babel/plugin-transform-numeric-separator](https://npm.io/package/@babel/plugin-transform-numeric-separator.md) ^7.29.7
- [@babel/plugin-transform-optional-chaining](https://npm.io/package/@babel/plugin-transform-optional-chaining.md) ^7.29.7
- [@babel/plugin-transform-class-static-block](https://npm.io/package/@babel/plugin-transform-class-static-block.md) ^7.29.7

## Recent versions

- 7.3.2 (latest) — 2026-11-09
- 7.3.3-next.35-experimental-ea0dc44 (experimental) — 2026-11-19
- 7.3.3-next.35 (next) — 2026-11-19
- 3.1.0-test.8 (test) — 2022-04-07
- 0.0.0-experimental-1539a86 (1539a86) — 2020-04-27
- 0.0.0-experimental-56e9ae8 (56e9ae8) — 2020-04-27
- 0.0.0-experimental-b690b68 (b690b68) — 2020-04-27
- 0.0.0-experimental-f83134d (f83134d) — 2020-04-27
- 0.0.0-experimental-5db9029 (5db9029) — 2020-04-24
- 0.0.0-experimental-24f6ac8677d52a91e787a5e03726b5e96ce5e12c (24f6ac8677d52a91e787a5e03726b5e96ce5e12c) — 2020-04-24
- 7.3.3-next.35-experimental-aab0b34 — 2026-11-19
- 7.3.3-next.34 — 2026-11-19
- 7.3.3-next.33 — 2026-11-18
- 7.3.3-next.32 — 2026-11-18
- 7.3.3-next.30-experimental-f59888d — 2026-11-18
- … 2355 more at https://npm.io/package/@forge/bundler/versions

## README

# 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](https://webpack.js.org/) 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](https://developer.atlassian.com/platform/forge/runtime-reference/#javascript-environment).
Accessing those at runtime would throw an error.

Where possible, the unavailable modules and globals are replaced with
compatible implementations using
[ProvidePlugin](https://webpack.js.org/plugins/provide-plugin/) and
[`alias`](https://webpack.js.org/configuration/resolve/#resolvealias). 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](https://github.com/defunctzombie/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](https://hello.atlassian.net/wiki/spaces/ECO/pages/1767953090/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](https://webpack.js.org/plugins/banner-plugin/) 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](https://webpack.js.org/plugins/provide-plugin/).

### Native UI

TODO: Not documented

---
_Source: https://npm.io/package/@forge/bundler · Machine-readable twin of the npm.io package page. Health data is recomputed on every publish._
