esbuild-plugin-ts-references

0.2.2 verified Mon Apr 27 auth: no javascript

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.

Common errors

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

cause Package not installed or missing from node_modules.

fix

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

error TypeError: tsReferences is not a function ↓

cause 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 ERROR: Could not resolve 'my-referenced-package' ↓

cause 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.

Warnings

gotcha The 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.

gotcha The 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.

deprecated The 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.

gotcha The plugin does not handle circular references between TypeScript projects. ↓

fix Restructure your project references to avoid circular dependencies.

gotcha The 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.

Install

npm install esbuild-plugin-ts-references

yarn add esbuild-plugin-ts-references

pnpm add esbuild-plugin-ts-references

Imports

default

wrong

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

correct

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

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

default

wrong

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

correct

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

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

tsReferences

wrong

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

correct

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

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

Quickstart

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()],
});