Registry / devops / esbuild-plugin-ts-references

esbuild-plugin-ts-references

library0.2.2jsnpmunverified

An esbuild plugin that resolves TypeScript project references (composite projects) during bundling. Version 0.2.2 is the latest stable release, with no frequent updates. Unlike tsc --build which natively supports references, esbuild does not; this plugin fills that gap by reading tsconfig.json and package.json to map referenced packages to their output directories. It is lightweight and focuses solely on this task, with no dependencies beyond esbuild.

devops

npm install esbuild-plugin-ts-references

github ↗package ↗

INSTALL

IMPORT

SIG · ESBUILD-PLUGIN-TS-

esbuild-plugin-ts-references

devopsjavascriptv0.2.2

Install

—

Import

—

Disk

—

Pass rate

0/ 6

Env Coverage0 / 6

glibc

18–22

musl

18–22

Install & Compatibility

Where this runs

tested against v? · npm install

Install × environment matrix

Each cell = how many times install + import succeeded across repeated harness runs. Partial = flaky.
glibc = Debian/Ubuntu slim · musl = Alpine Linux

musl

node 18–223 runs

build_error

glibc

node 18–223 runs

build_error

Code

Verified usage

Verified import paths — ran on the pinned version, not inferred.

default

✓ import tsReferences from 'esbuild-plugin-ts-references'

✗ const tsReferences = require('esbuild-plugin-ts-references').default

Package ships both ESM and CJS; default export is the plugin function.

default

✓ const tsReferences = require('esbuild-plugin-ts-references')

✗ const { tsReferences } = require('esbuild-plugin-ts-references')

In CommonJS, require gives the plugin function directly; destructuring is incorrect.

tsReferences

✓ import tsReferences from 'esbuild-plugin-ts-references'

✗ import { tsReferences } from 'esbuild-plugin-ts-references'

The package has a default export, not a named export.

Shows minimal setup: import the plugin, call it in the esbuild plugins array, and bundle a TypeScript file with project references.

import esbuild from 'esbuild'; import tsReferences from 'esbuild-plugin-ts-references'; await esbuild.build({ entryPoints: ['src/index.ts'], bundle: true, outfile: 'dist/bundle.js', plugins: [tsReferences()], });

Debug

Known issues

gotchaThe plugin currently only resolves references based on the closest tsconfig.json relative to the entry point. It does not support custom paths or complex monorepo structures.

fix

Ensure your project references are set up with relative paths in tsconfig.json and package.json.

affects: >=0.0.0

gotchaThe plugin ignores the composite option in tsconfig.json; it assumes references point to built output directories. If your references don't have outDir set, the plugin may fail.

fix

Check that each referenced project has a rootDir and outDir specified in its tsconfig.json.

affects: >=0.0.0

deprecatedThe plugin may stop working with future esbuild versions if esbuild changes its plugin API. Currently compatible with esbuild >= 0.14.21.

fix

Keep esbuild version pinned within the supported range, or watch for plugin updates.

affects: <0.3.0

gotchaThe plugin does not handle circular references between TypeScript projects.

fix

Restructure your project references to avoid circular dependencies.

affects: >=0.0.0

gotchaThe plugin does not support referenced projects that use different module systems (CJS vs ESM). It assumes the referenced output is compatible with the parent bundle format.

fix

Ensure all referenced projects are compiled to the same module format expected by the parent bundle.

affects: >=0.0.0

Errors

Common errors & fixes

Error: Cannot find module 'esbuild-plugin-ts-references'

Package not installed or missing from node_modules.

fix

Run 'npm install --save-dev esbuild-plugin-ts-references'

TypeError: tsReferences is not a function

Incorrect import style; using default import as a named import often yields undefined at runtime.

fix

Use const tsReferences = require('esbuild-plugin-ts-references') for CJS or import tsReferences from 'esbuild-plugin-ts-references' for ESM.

ERROR: Could not resolve 'my-referenced-package'

The plugin couldn't find the referenced package in node_modules or the reference path in tsconfig.json is incorrect.

fix

Verify that the referenced project is listed in tsconfig.json's references array and that its package.json exports the main field correctly.

Upgrade

Version history

0.2.2latest on npm

Audit

Dependencies

esbuildrequiredPeer dependency; the plugin runs as an esbuild plugin and requires esbuild >= 0.14.21

Agent activity

4 hits · last 30 days

node

Resources

githubhttps://github.com/smacker/esbuild-plugin-ts-references ↗

packagehttps://www.npmjs.com/package/esbuild-plugin-ts-references ↗