{"id":13133,"library":"esbuild-node-tsc","title":"esbuild-node-tsc","description":"esbuild-node-tsc is a CLI tool designed to rapidly build TypeScript Node.js projects leveraging the performance of esbuild. Currently at version 2.0.5, the project maintains an active release cadence, frequently updating dependencies and introducing minor features or fixes. Its primary function is to interpret tsconfig.json options and apply them via esbuild, offering significantly faster build times compared to tsc or ts-node for development workflows. A key differentiator is its focus on build speed rather than type-checking, which it explicitly offloads to tsc. It provides prebuild and postbuild hooks for custom operations like cleaning output directories or copying non-TypeScript assets, which became the standard approach since version 2.0.0, replacing automatic file copying.","status":"active","version":"2.0.5","language":"javascript","source_language":"en","source_url":"https://github.com/a7ul/esbuild-node-tsc","tags":["javascript","esbuild","node","dev","tsnode","ts-node","tsc","typescript"],"install":[{"cmd":"npm install esbuild-node-tsc","lang":"bash","label":"npm"},{"cmd":"yarn add esbuild-node-tsc","lang":"bash","label":"yarn"},{"cmd":"pnpm add esbuild-node-tsc","lang":"bash","label":"pnpm"}],"dependencies":[{"reason":"Core bundler dependency for processing TypeScript files.","package":"esbuild","optional":false},{"reason":"Required for type definitions and tsconfig.json parsing.","package":"typescript","optional":false}],"imports":[{"note":"For programmatic use, typically for custom build scripts or integration. The package primarily functions as a CLI tool.","wrong":"const build = require('esbuild-node-tsc').build;","symbol":"build","correct":"import { build } from 'esbuild-node-tsc';"},{"note":"For programmatic watch mode, allowing continuous rebuilding on file changes. The package primarily functions as a CLI tool.","wrong":"const watch = require('esbuild-node-tsc').watch;","symbol":"watch","correct":"import { watch } from 'esbuild-node-tsc';"},{"note":"Import as a type for strongly typing the configuration object in 'etsc.config.js' when writing it in TypeScript.","wrong":"import { ETSCConfig } from 'esbuild-node-tsc';","symbol":"ETSCConfig","correct":"import type { ETSCConfig } from 'esbuild-node-tsc';"}],"quickstart":{"code":"{\n  \"name\": \"my-project\",\n  \"version\": \"1.0.0\",\n  \"scripts\": {\n    \"dev\": \"nodemon\",\n    \"build\": \"etsc --config etsc.config.js\"\n  },\n  \"devDependencies\": {\n    \"esbuild\": \"^0.19.0\",\n    \"esbuild-node-tsc\": \"^2.0.0\",\n    \"nodemon\": \"^3.0.0\",\n    \"typescript\": \"^5.0.0\",\n    \"cpy\": \"^11.0.0\",\n    \"rimraf\": \"^5.0.0\",\n    \"express\": \"^4.18.2\",\n    \"@types/express\": \"^4.17.21\",\n    \"@types/node\": \"^20.0.0\"\n  }\n}\n\n// nodemon.json\n{\n  \"watch\": [\"src\"],\n  \"ignore\": [\"src/**/*.test.ts\"],\n  \"ext\": \"ts,mjs,js,json,graphql\",\n  \"exec\": \"etsc && node ./dist/index.js\",\n  \"legacyWatch\": true\n}\n\n// etsc.config.js\nmodule.exports = {\n  esbuild: {\n    minify: false,\n    target: \"es2022\"\n  },\n  prebuild: async () => {\n    const rimraf = (await import(\"rimraf\")).default;\n    console.log(\"Cleaning dist folder...\");\n    rimraf.sync(\"./dist\");\n  },\n  postbuild: async () => {\n    const cpy = (await import(\"cpy\")).default;\n    console.log(\"Copying non-TS assets...\");\n    await cpy(\n      [\n        \"src/**/*.graphql\",\n        \"src/**/*.json\",\n        \"!src/**/*.{tsx,ts,js,jsx}\"\n      ],\n      \"dist\"\n    );\n  }\n};\n\n// src/index.ts\nimport express from 'express';\n\nconst app = express();\nconst port = process.env.PORT || 3000;\n\napp.get('/', (req, res) => {\n  res.send('Hello from esbuild-node-tsc!');\n});\n\napp.listen(port, () => {\n  console.log(`Server running at http://localhost:${port}`);\n});\n","lang":"typescript","description":"Demonstrates setting up esbuild-node-tsc for a TypeScript Node.js project with live reloading using nodemon, including custom prebuild/postbuild hooks for cleaning the dist folder and copying non-TypeScript assets like `.graphql` and `.json` files. This setup enables rapid development feedback loops."},"warnings":[{"fix":"Migrate to using 'prebuild' and 'postbuild' hooks in 'etsc.config.js'. Install 'cpy' and 'rimraf' as dev dependencies if needed for these hooks (e.g., `npm install --save-dev cpy rimraf`).","message":"Version 2.0.0 removed 'cpy' and 'rimraf' as direct dependencies and no longer performs automatic non-source file copying. Users must now implement custom prebuild and postbuild hooks in 'etsc.config.js' to handle cleaning output directories or copying assets.","severity":"breaking","affected_versions":">=2.0.0"},{"fix":"Run 'tsc --noEmit' in parallel or as a separate step in your build process (e.g., in `package.json` scripts) to ensure type safety. For example, `npm run build && tsc --noEmit`.","message":"esbuild-node-tsc does not perform type checking. It focuses solely on fast compilation. Any type errors in your project will not be reported by 'etsc', which can lead to runtime issues if not caught elsewhere.","severity":"gotcha","affected_versions":">=1.0.0"},{"fix":"Ensure both 'esbuild' and 'typescript' are installed as dev dependencies: `npm install --save-dev esbuild typescript`.","message":"The package requires 'esbuild' and 'typescript' as peer dependencies. Failure to install these explicitly in your project will result in 'Module not found' or 'Cannot find package' errors during execution.","severity":"gotcha","affected_versions":">=1.0.0"},{"fix":"Review the 'esbuild' options in your 'etsc.config.js' and consult the esbuild documentation to understand their implications, ensuring they align with your desired build behavior and 'tsconfig.json' settings.","message":"When using 'etsc.config.js', pay attention to the 'esbuild' property. Options specified here will override those inferred from 'tsconfig.json', potentially leading to unexpected build outputs or behavior if not carefully managed.","severity":"gotcha","affected_versions":">=1.0.0"}],"env_vars":null,"last_verified":"2026-04-19T00:00:00.000Z","next_check":"2026-07-18T00:00:00.000Z","problems":[{"fix":"Run `npm install --save-dev esbuild` to install the esbuild package locally.","cause":"The 'esbuild' peer dependency is not installed in the project's 'devDependencies'.","error":"Error: Cannot find module 'esbuild' or its corresponding type declarations."},{"fix":"Ensure `esbuild-node-tsc` is installed via `npm install --save-dev esbuild-node-tsc` and execute it using `npx etsc` or via a `package.json` script (e.g., `npm run dev`).","cause":"The 'esbuild-node-tsc' package is not installed as a local dev dependency or the `npx` command cannot find it.","error":"command not found: etsc"},{"fix":"Ensure 'rimraf' and 'cpy' are installed as dev dependencies. For 'etsc.config.js' hooks, use dynamic `await import('module')` as shown in the package's documentation to load ESM modules correctly.","cause":"Attempting to use a dynamically imported ESM module (like 'rimraf' or 'cpy') synchronously or incorrectly within a CommonJS `etsc.config.js`, or the module itself is not installed.","error":"TypeError: Cannot read properties of undefined (reading 'sync') at file:///path/to/etsc.config.js"},{"fix":"Integrate a separate step for type checking using `tsc --noEmit` into your development or CI/CD workflow to validate types independently of the build process.","cause":"esbuild-node-tsc intentionally bypasses TypeScript's type checking for speed, focusing only on efficient code transpilation.","error":"TypeScript compile errors are not reported after running 'etsc' command, but 'tsc' shows errors when run separately."}],"ecosystem":"npm","meta_description":null,"install_score":null,"install_tag":null,"quickstart_score":null,"quickstart_tag":null,"pypi_latest":null,"cli_name":"esbuild-node-tsc"}