compilePackages: computed require(expr) throws ReferenceError (createRequire works)

[jdalton]

Hit this compiling a TS library with compilePackages. A literal require('pkg') gets rewritten to an import, but a computed require(specifier) (non-literal arg) can't be rewritten statically — and there's no ambient require in the compiled output, so it throws ReferenceError at runtime.

typeof require is 'undefined' in both the entry and the compiled package modules, and createRequire(import.meta.url) from a named module import works — so there's an easy workaround. Could compiled modules expose a createRequire-backed require so dynamic require() keeps working out of the box?

Minimal repro

package.json

{ "name": "app", "private": true, "perry": { "compilePackages": ["mylib"], "allow": { "compilePackages": ["mylib"] } } }

node_modules/mylib/package.json

{ "name": "mylib", "version": "1.0.0", "main": "./src/index.ts", "exports": { ".": "./src/index.ts" } }

node_modules/mylib/src/index.ts

import { createRequire } from 'module'

export function probe(): string {
  const spec = ['n', 'o', 'd', 'e', ':', 'o', 's'].join('') // computed -> not rewritable
  let viaRequire: string
  try {
    require(spec)
    viaRequire = 'require(computed) ok'
  } catch (e) {
    viaRequire = 'require(computed) threw ' + (e as Error).name
  }
  const req = createRequire(import.meta.url)
  return `typeof require=${typeof require} | ${viaRequire} | createRequire=${typeof req(spec)}`
}

entry.ts

import { probe } from 'mylib'

throw new Error(probe())

perry compile entry.ts -o app && ./app prints:

typeof require=undefined | require(computed) threw ReferenceError | createRequire=function

Thanks for the great work on this!

[jdalton]

Workaround for anyone hitting this before it's fixed upstream: import createRequire as a named import from the bare module specifier and bind a require yourself — ambient when it exists, createRequire(import.meta.url) otherwise.

import { createRequire } from 'module'

function bindRequire(): ((id: string) => unknown) | undefined {
  // Ambient require exists in CJS; in ESM / compiled package modules it doesn't.
  if (typeof require === 'function') {
    return require
  }
  if (typeof createRequire === 'function') {
    try {
      return createRequire(import.meta.url) as (id: string) => unknown
    } catch {
      return undefined
    }
  }
  return undefined
}

// Computed specifier now works in a compiled package module:
const req = bindRequire()
const mod = req ? req(someComputedSpecifier) : undefined

Two things that made this clean under compilePackages:

• The named imports from the bare module specifier (createRequire, and isBuiltin if you need it) resolve fine in compiled modules — it's only ambient require that's missing. Using the bare module (not node:module) also keeps the same source browser-bundleable, where a bundler stubs module away.
• bindRequire() returns undefined off-runtime instead of throwing, so the same code path is safe everywhere.

Thanks again for the great work on this.

[jdalton]

One caveat on the workaround above, since require is directory-specific: createRequire(base) resolves relative specifiers (./x, ../y) from base's directory.

• For builtins (node:os) and bare packages, the base is irrelevant — they resolve the same anywhere, so a require bound to any fixed module works.
• For a relative specifier, bind to the calling module's import.meta.url, not some shared helper's. A require bound to helper.ts would resolve ../x from helper.ts's directory, not the caller's. Bundled, everything collapses to one base and either works; compiling from source (unbundled), each module sits at its own nested path, so the base matters.

So for relative loads: createRequire(callerImportMetaUrl)(relativeSpecifier).

[proggeramlug]

hey @jdalton ,

Thanks for the great repro and the follow-up notes on the relative-specifier caveat, both were spot-on.

You've actually surfaced two things, so I've split them into a tracked plan in #5389:

Tier 1 (closes this issue): We'll give compiled compilePackages modules an ambient require backed by createRequire, instead of letting a bare/computed require fall through to a ReferenceError. Since your computed specifier resolves to a builtin (node:os), this makes your require(spec) path work out of the box — our runtime require already resolves builtins by string. The runtime backing exists; it's a small lowering change, gated to external/compilePackages modules (in first-party source the "use a static import" compile error is deliberate and stays).

One honesty note worth flagging: for a computed specifier that resolves to a real package (not a builtin), Tier 1 changes the failure from a confusing ReferenceError into a descriptive "unsupported" error rather than making it work - see below.

Tier 2 (follow-on): Extending computed require to actual packages/relative paths, but bounded by the AOT model. A native binary can only require modules that were discovered and linked at compile time — so we can support const-foldable / globbable specifiers (require(`./plugins/${name}`), require(cond ? 'a' : 'b')) by reusing the same resolver that already powers dynamic import(). A genuinely runtime-computed package string (e.g. building the name from ['n','o',…].join('')) can't resolve in an AOT binary, the same way dynamic import() of a computed path can't - that stays unsupported by design.

Your bindRequire() workaround is the right call in the meantime, and the relative-vs-builtin base distinction you noted is exactly correct. Tracking the work in #5389.

[proggeramlug]

The PR just landed which should clear your workaround.

Note this is just on main, so either wait for the next release or compile from main :)

[jdalton]

@proggeramlug I noticed the npm releases are different from main releases. Is that something sticky on the npm side or just lack of automation helpers (so it's a manual pain)?

[jdalton]

Also thank you! @proggeramlug

[proggeramlug]

@jdalton Good catch, it was neither npm-side stickiness nor missing automation. The release pipeline ran every time; the artifacts just physically exceeded npm's size cap.

Fixed in #5145 : the .a archives are now zstd-compressed (~3.7x smaller, transparently decompressed into a per-user cache on first link). As of v0.5.1182, all five platform packages are published in ockstep again - npm now tracks main within the normal patch-bump lag.

[jdalton]

Ah yes! This may also impact the number of versions you can release, for smaller npm sizes you might go with a hybrid npm package that downloads github release payloads

[jdalton]

See https://x.com/jdalton/status/2067316116825768187 for the limit(ed|ing number of releases issue.

[proggeramlug]

@jdalton Thanks for bringing this up, wasn't even aware! Yes; we'll adjust our npm strategy shortly!

[jdalton]

More info on the metadata limitation: vercel/next.js#94953