{"id":21280,"library":"esbuild-plugin-ts-references","title":"esbuild-plugin-ts-references","description":"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.","status":"active","version":"0.2.2","language":"javascript","source_language":"en","source_url":"https://github.com/smacker/esbuild-plugin-ts-references","tags":["javascript","esbuild","plugin","typescript"],"install":[{"cmd":"npm install esbuild-plugin-ts-references","lang":"bash","label":"npm"},{"cmd":"yarn add esbuild-plugin-ts-references","lang":"bash","label":"yarn"},{"cmd":"pnpm add esbuild-plugin-ts-references","lang":"bash","label":"pnpm"}],"dependencies":[{"reason":"Peer dependency; the plugin runs as an esbuild plugin and requires esbuild >= 0.14.21","package":"esbuild","optional":false}],"imports":[{"note":"Package ships both ESM and CJS; default export is the plugin function.","wrong":"const tsReferences = require('esbuild-plugin-ts-references').default","symbol":"default","correct":"import tsReferences from 'esbuild-plugin-ts-references'"},{"note":"In CommonJS, require gives the plugin function directly; destructuring is incorrect.","wrong":"const { tsReferences } = require('esbuild-plugin-ts-references')","symbol":"default","correct":"const tsReferences = require('esbuild-plugin-ts-references')"},{"note":"The package has a default export, not a named export.","wrong":"import { tsReferences } from 'esbuild-plugin-ts-references'","symbol":"tsReferences","correct":"import tsReferences from 'esbuild-plugin-ts-references'"}],"quickstart":{"code":"import esbuild from 'esbuild';\nimport tsReferences from 'esbuild-plugin-ts-references';\n\nawait esbuild.build({\n  entryPoints: ['src/index.ts'],\n  bundle: true,\n  outfile: 'dist/bundle.js',\n  plugins: [tsReferences()],\n});","lang":"typescript","description":"Shows minimal setup: import the plugin, call it in the esbuild plugins array, and bundle a TypeScript file with project references."},"warnings":[{"fix":"Ensure your project references are set up with relative paths in tsconfig.json and package.json.","message":"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.","severity":"gotcha","affected_versions":">=0.0.0"},{"fix":"Check that each referenced project has a rootDir and outDir specified in its tsconfig.json.","message":"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.","severity":"gotcha","affected_versions":">=0.0.0"},{"fix":"Keep esbuild version pinned within the supported range, or watch for plugin updates.","message":"The plugin may stop working with future esbuild versions if esbuild changes its plugin API. Currently compatible with esbuild >= 0.14.21.","severity":"deprecated","affected_versions":"<0.3.0"},{"fix":"Restructure your project references to avoid circular dependencies.","message":"The plugin does not handle circular references between TypeScript projects.","severity":"gotcha","affected_versions":">=0.0.0"},{"fix":"Ensure all referenced projects are compiled to the same module format expected by the parent bundle.","message":"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.","severity":"gotcha","affected_versions":">=0.0.0"}],"env_vars":null,"last_verified":"2026-04-27T00:00:00.000Z","next_check":"2026-07-26T00:00:00.000Z","problems":[{"fix":"Run 'npm install --save-dev esbuild-plugin-ts-references'","cause":"Package not installed or missing from node_modules.","error":"Error: Cannot find module 'esbuild-plugin-ts-references'"},{"fix":"Use const tsReferences = require('esbuild-plugin-ts-references') for CJS or import tsReferences from 'esbuild-plugin-ts-references' for ESM.","cause":"Incorrect import style; using default import as a named import often yields undefined at runtime.","error":"TypeError: tsReferences is not a function"},{"fix":"Verify that the referenced project is listed in tsconfig.json's references array and that its package.json exports the main field correctly.","cause":"The plugin couldn't find the referenced package in node_modules or the reference path in tsconfig.json is incorrect.","error":"ERROR: Could not resolve 'my-referenced-package'"}],"ecosystem":"npm","meta_description":null,"install_score":null,"install_tag":null,"quickstart_score":null,"quickstart_tag":null}