parcel-bundler/parcel · error · Error

Scope hoisting is not supported with SSG

Error message

Scope hoisting is not supported with SSG

What it means

Thrown by the react-static SSG packager when a bundle has `shouldScopeHoist` enabled. Static site generation loads the bundle into a module sandbox (via `loadBundle`) and renders it server-side; the scope-hoisting packaging format is incompatible with that loader, so the combination is rejected up front.

Source

Thrown at packages/packagers/react-static/src/ReactStaticPackager.js:116

      includeInline: false,
      includeIsolated: false,
    })) {
      if (b.type === 'js') {
        referencedBundles.push(b.getContentHash());
      }
    }

    return {pages, referencedBundles};
  },
  async package({
    bundle,
    bundleGraph,
    getInlineBundleContents,
    config,
    bundleConfig,
  }) {
    if (bundle.env.shouldScopeHoist) {
      throw new Error('Scope hoisting is not supported with SSG');
    }

    let {load, loadModule} = await loadBundle(
      bundle,
      bundleGraph,
      getInlineBundleContents,
    );

    let Component = load(nullthrows(bundle.getMainEntry()).id).default;
    let {renderToReadableStream} = loadModule(
      'react-server-dom-parcel/server.edge',
      __filename,
      'react-server',
    );
    let {prerender} = loadModule(
      'react-dom/static.edge',
      __filename,
      'react-client',

View on GitHub (pinned to 59484858a1)

Solutions

1. Disable scope hoisting for the SSG target: set `scopeHoist: false` (or omit/`--no-scope-hoist`) for that target.
2. Keep scope hoisting only on non-SSG (browser) targets via per-target configuration.
3. If you need smaller SSG output, use a different optimization (minification, tree-shaking) rather than scope hoisting.

Example fix

// before — .parcelrc or target config
{ "targets": { "ssg": { "source": "src/ssg.js", "scopeHoist": true } } }
// after
{ "targets": { "ssg": { "source": "src/ssg.js", "scopeHoist": false } } }

function assertSSGCompat(env) {
  if (env.isSSG && env.shouldScopeHoist) {
    throw new Error('SSG targets cannot enable scope hoisting');
  }
}

function isSSGTarget(bundle) { return bundle?.target?.sourceType === 'react-static' || !!bundle?.env?.isSSG; }

When it happens

Trigger: Setting `scopeHoist: true` (or enabling scope hoisting via a target/CLI flag) on a build that uses the react-static packager (SSG target). Mixing the `--no-scope-hoist` default with an SSG target that someone re-enabled hoisting on.

Common situations: Copying a production web target's config (which enables scope hoisting) onto an SSG target; toggling scope hoisting globally without per-target overrides; upgrading and inheriting a hoist-enabled default for the SSG bundle.

Related errors

• Scope hoisting cannot be disabled for library targets.
• External modules are not supported when building for browser
• Library targets are not supported in serve mode.
• Expected package.json file in ${rootDir}
• Unexpected output file type ${ext} in target "${targetName}"

AI-assisted analysis of parcel-bundler/parcel@59484858a1 (2026-08-13). Data as JSON: /api/errors/494ef87ab25e6c24. Report an issue: GitHub.