Run webpack bundles in Node.js with optional VM sandboxing

Discover other projects

Bundle Runner

npm version npm downloads Github Actions Codecov Dependencies

This package allows running a Webpack bundle in Node.js with optional sandboxed context. Useful for development, loading bundle from memory (HMR) and a consistent way of loading bundle between development and production environments.

āœ… What sandboxing is for:

  • Optional sandboxing using Node.js VM
  • Mitigate script evaluation side-effects to global object
  • Avoid unwanted shared state
  • Avoid memory leaks during HMR

āŒ What sandboxing is not for:

  • Fully avoid side effects of evaluation
  • A secure sandbox to run untrusted code
  • High performance


yarn add bundle-runner

npm install bundle-runner


import { createBundle } from 'bundle-runner'

const { evaluateEntry } = createBundle('path/to/bundle.json')

const entry = evaluateEntry(context)


function createBundle(bundle: Partial<Bundle> | string, options?: CreateBundleOptions): {
    bundle: Bundle;
    evaluateEntry: (context: object) => any;
    evaluateModule: (filename: string, context: object) => any;
    rewriteErrorTrace: (err: Error) => Promise<Error>;


type CreateBundleOptions = {
    basedir?: string;
    runInNewContext?: 'once' | boolean;
    runningScriptOptions?: VM.RunningScriptOptions;

Bundle Format

Input can be string (path to a .js file or .json file with bundle format) or directly bundle object with type of:

type Bundle = {
    basedir: string;
    entry: string;
    files: {
        [filename: string]: string
    maps: {
        [filename: string]: string

SourceMap Support

After creating bundle, a rewriteErrorTrace utility is exposed which you can use to rewrite traces:

const { evaluateEntry, rewriteErrorTrace } = createBundle('path/to/bundle.json')

try {
  const entry = evaluateEntry(context)
  const app = await entry({})
} catch (err) {
  await rewriteErrorTrace(err)
  throw err


Inspired by vue-server-renderer made by Evan You.