@freckle/tsconfig

Shared TypeScript compiler options for Freckle repositories. Three files: a base both archetypes agree on, and one small overlay each.

| File | Use in | Adds | | --- | --- | --- | | base.json | nothing directly | the 13 shared flags | | action.json | typescript-github-action repos | removeComments | | library.json | js-library repos | declaration |

Where the base came from

It is not a new opinion. It is the intersection of two clusters that converged on the same flags independently: all ten typescript-github-action repos are unanimous on these thirteen, and five js-library repos carry them byte-identically. Adopting the base changes nothing for either group.

Why removeComments is Action-only

It strips comments from .d.ts output, not just from .js. On a library that deletes every JSDoc block from the published types, so a consumer loses hover text, parameter hints and property documentation. Measured on a probe with declaration: true:

// without removeComments                  // with removeComments
/**                                        export declare function add(
 * Adds two numbers.                         a: number,
 * @param a the first number                 b: number
 * @returns the sum                        ): number;
 */                                        export type Point = {
export declare function add(                   x: number;
  a: number,                                   y: number;
  b: number                                };
): number;
export type Point = {
    /** horizontal offset */
    x: number;
};

Actions are unaffected: they do not set declaration, so there is no .d.ts, and the ncc bundle that ships is read by machines. The fleet already splits this way — removeComments is set in ten repos, all of them Actions and none of them libraries.

Do not hoist it into base.json.

Use

pnpm add -D @freckle/tsconfig

{
  "extends": "@freckle/tsconfig/action.json",
  "compilerOptions": {
    "rootDir": "./src",
    "outDir": "./lib",
    "types": ["node", "vitest/globals"]
  },
  "include": ["./src/**/*"]
}

What stays in your repo, and why it has to

Compiler flags only live here. extends resolves a relative path against the file that declares it, so a path written in this package would resolve inside node_modules/@freckle/tsconfig/, not in your repo. These keys must stay local:

• rootDir, outDir, declarationDir, tsBuildInfoFile
• include, exclude, files
• baseUrl, paths, typeRoots

types is a list of package names rather than paths, so it would technically inherit — it stays local anyway because it says what a repo's tests and runtime pull in (node, vitest/globals, jquery), which is not a shared decision.

Overriding a flag

Set it in your own compilerOptions; the local value wins. Record why in the file, the way parser-js does for needing DOM in lib:

{
  "extends": "@freckle/tsconfig/library.json",
  "compilerOptions": {
    // Consumed in browser contexts, so DOM types are needed. Additive, not a
    // weakening of the shared set.
    "lib": ["ES2023", "DOM"]
  }
}

Note lib and types replace rather than merge, so an override has to restate the shared value alongside the addition.

Changing the base

Edit base.json here. Every consumer picks it up on its next dependency bump. A change to the base changes what the fleet type-checks, so it is a real decision rather than a formatting fix — say what breaks and what it catches.