{"id":10593,"library":"broccoli-typescript-compiler","title":"Broccoli TypeScript Compiler","description":"Broccoli TypeScript Compiler (broccoli-typescript-compiler) is a specialized Broccoli plugin designed to integrate TypeScript compilation directly into a Broccoli.js build pipeline. Currently stable at version 8.0.0, this package provides robust tooling for converting TypeScript files into JavaScript, supporting both CommonJS and ES modules targets. It allows for flexible configuration via `tsconfig.json` files or inline objects, enabling developers to define compiler options such as module resolution, target ES version, source maps, and declaration file generation. Key differentiators include its tight integration with the Broccoli ecosystem, offering three distinct usage patterns: a direct compilation function, a class-based compiler for more control, and a filter function that intelligently processes only TypeScript files while passing non-TypeScript assets through. While a specific release cadence isn't published, the project actively maintains compatibility with recent TypeScript versions, ensuring it remains a viable solution for Broccoli-based projects requiring TypeScript support.","status":"active","version":"8.0.0","language":"javascript","source_language":"en","source_url":"https://github.com/tildeio/broccoli-typescript-compiler","tags":["javascript","TypeScript","broccoli-plugin","compiler","js","typescript"],"install":[{"cmd":"npm install broccoli-typescript-compiler","lang":"bash","label":"npm"},{"cmd":"yarn add broccoli-typescript-compiler","lang":"bash","label":"yarn"},{"cmd":"pnpm add broccoli-typescript-compiler","lang":"bash","label":"pnpm"}],"dependencies":[{"reason":"Required for TypeScript compilation. Must be installed as a peer dependency.","package":"typescript","optional":false}],"imports":[{"note":"The primary function export for direct compilation. CommonJS users should access it via `.default` (e.g., `require('broccoli-typescript-compiler').default`).","wrong":"const typescript = require('broccoli-typescript-compiler');","symbol":"default","correct":"import typescript from 'broccoli-typescript-compiler';"},{"note":"Provides the class-based API for creating a compiler instance. CommonJS users will access it directly as a named export.","wrong":"const TypescriptCompiler = require('broccoli-typescript-compiler').TypescriptCompiler;","symbol":"TypescriptCompiler","correct":"import { TypescriptCompiler } from 'broccoli-typescript-compiler';"},{"note":"A utility function that compiles only TypeScript files from the input tree and merges them with non-TS files. CommonJS users will access it directly as a named export.","wrong":"const filterTypescript = require('broccoli-typescript-compiler').filterTypescript;","symbol":"filterTypescript","correct":"import { filterTypescript } from 'broccoli-typescript-compiler';"}],"quickstart":{"code":"import typescript from 'broccoli-typescript-compiler';\nimport funnel from 'broccoli-funnel';\nimport mergeTrees from 'broccoli-merge-trees';\nimport { createRequire } from 'module';\n\nconst require = createRequire(import.meta.url);\nconst inputTree = funnel('.', { exclude: ['node_modules/**', 'dist/**'] });\n\nconst compiledJS = typescript(inputTree, {\n  tsconfig: {\n    compilerOptions: {\n      module: 'commonjs',\n      target: 'es2018',\n      moduleResolution: 'node',\n      newLine: 'LF',\n      rootDir: '.', // Assuming root directory\n      outDir: 'dist',\n      sourceMap: true,\n      declaration: true,\n    },\n    files: ['index.ts', 'src/**/*.ts'], // Adjust files as needed for your project\n  },\n  throwOnError: process.env.NODE_ENV === 'production',\n  annotation: 'Compile application TypeScript',\n});\n\n// Example of merging compiled JS with other assets if needed\nexport default mergeTrees([compiledJS /*, otherTrees */], { overwrite: true });","lang":"typescript","description":"Demonstrates compiling TypeScript files within a Broccoli build, using a custom tsconfig and handling production error settings."},"warnings":[{"fix":"Be aware of the `NODE_ENV` impact. To always allow non-breaking errors regardless of `NODE_ENV`, you may need to explicitly set `throwOnError: false` and ensure `process.env.NODE_ENV` is not 'production' if you intend for errors to be non-fatal.","message":"The `throwOnError` option defaults to `true` when `process.env.NODE_ENV` is set to 'production', even if explicitly set to `false` in configuration. This can cause unexpected build failures in production environments if not anticipated.","severity":"gotcha","affected_versions":">=1.0.0"},{"fix":"Always follow the 'How to upgrade `typescript`' instructions in the project's README when updating the `typescript` peer dependency. This typically involves `git submodule update --init`, updating `package.json`, running `yarn run generate-tsconfig-interface`, and updating the `vendor/typescript` submodule.","message":"Upgrading the peer dependency `typescript` to a new major version often requires specific maintenance steps, including updating submodules and running `yarn run generate-tsconfig-interface`. Neglecting these steps can lead to compilation issues or incorrect type resolution.","severity":"breaking","affected_versions":">=1.0.0"},{"fix":"Ensure you are integrating this package within a Broccoli.js `Brocfile.js` or a similar Broccoli-managed build process. For standalone TypeScript compilation, use the `typescript` package directly.","message":"This package is a Broccoli plugin and is only useful within a Broccoli.js build pipeline. It is not a standalone TypeScript compiler for general-purpose use outside of the Broccoli ecosystem.","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":"Install the required `typescript` version: `npm install typescript@^4.0.3` (or the version specified in peerDependencies) in your project.","cause":"The `typescript` package, a peer dependency, is not installed or its version does not meet the specified range.","error":"Cannot find module 'typescript' or its corresponding type declarations."},{"fix":"Review the `[ERROR_MESSAGE]` output for specific TypeScript errors. Fix the TypeScript code issues, or set `throwOnError: false` (being mindful of the `NODE_ENV` default override) if you want to allow the build to proceed with errors.","cause":"`throwOnError` is enabled (either explicitly or due to `NODE_ENV='production'`), and TypeScript reported errors during compilation.","error":"TypeScript compilation failed: [ERROR_MESSAGE]"},{"fix":"Ensure `tsconfig` is either an absolute path string to a `tsconfig.json` file or a valid JavaScript object matching the structure of `tsconfig.json`'s `compilerOptions` and other root-level properties.","cause":"The `tsconfig` option was provided in an incorrect format or was missing required properties.","error":"Error: The 'tsconfig' option must be a string path or a config object."}],"ecosystem":"npm"}