Broccoli TypeScript Compiler

Common errors

• Cannot find module 'typescript' or its corresponding type declarations.

  cause The `typescript` package, a peer dependency, is not installed or its version does not meet the specified range.
  fix Install the required `typescript` version: `npm install typescript@^4.0.3` (or the version specified in peerDependencies) in your project.

• TypeScript compilation failed: [ERROR_MESSAGE]

  cause `throwOnError` is enabled (either explicitly or due to `NODE_ENV='production'`), and TypeScript reported errors during compilation.
  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.

• Error: The 'tsconfig' option must be a string path or a config object.

  cause The `tsconfig` option was provided in an incorrect format or was missing required properties.
  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.

Warnings

• gotcha 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.
  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.
• breaking 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.
  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.
• gotcha 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.
  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.

Install

• npm install broccoli-typescript-compiler npm
• yarn add broccoli-typescript-compiler yarn
• pnpm add broccoli-typescript-compiler pnpm

Imports

• default
  wrong:

  const typescript = require('broccoli-typescript-compiler');

  correct:

  import typescript from 'broccoli-typescript-compiler';

  The primary function export for direct compilation. CommonJS users should access it via `.default` (e.g., `require('broccoli-typescript-compiler').default`).
• TypescriptCompiler
  wrong:

  const TypescriptCompiler = require('broccoli-typescript-compiler').TypescriptCompiler;

  correct:

  import { TypescriptCompiler } from 'broccoli-typescript-compiler';

  Provides the class-based API for creating a compiler instance. CommonJS users will access it directly as a named export.
• filterTypescript
  wrong:

  const filterTypescript = require('broccoli-typescript-compiler').filterTypescript;

  correct:

  import { filterTypescript } from 'broccoli-typescript-compiler';

  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.

Quickstart

Demonstrates compiling TypeScript files within a Broccoli build, using a custom tsconfig and handling production error settings.

import typescript from 'broccoli-typescript-compiler';
import funnel from 'broccoli-funnel';
import mergeTrees from 'broccoli-merge-trees';
import { createRequire } from 'module';

const require = createRequire(import.meta.url);
const inputTree = funnel('.', { exclude: ['node_modules/**', 'dist/**'] });

const compiledJS = typescript(inputTree, {
  tsconfig: {
    compilerOptions: {
      module: 'commonjs',
      target: 'es2018',
      moduleResolution: 'node',
      newLine: 'LF',
      rootDir: '.', // Assuming root directory
      outDir: 'dist',
      sourceMap: true,
      declaration: true,
    },
    files: ['index.ts', 'src/**/*.ts'], // Adjust files as needed for your project
  },
  throwOnError: process.env.NODE_ENV === 'production',
  annotation: 'Compile application TypeScript',
});

// Example of merging compiled JS with other assets if needed
export default mergeTrees([compiledJS /*, otherTrees */], { overwrite: true });