@gabegabegabe/tsconfig

This repository contains shareable TSConfig files to be used in TypeScript projects.

These configs are opinionated and tuned to a specific, modern toolchain: @tsconfig/strictest strictness, ESM + bundler module resolution, and a TypeScript >=6.0 floor. They are published for anyone to use, but they make no attempt to accommodate stacks other than the author's.

Usage

Install the package and its required peers:

bun add -D @gabegabegabe/tsconfig @tsconfig/strictest typescript

Then create a tsconfig.json and extend the config that matches what you are building:

{
	"extends": "@gabegabegabe/tsconfig/react-lib.json"
}

Some configs require additional peers (see Requirements) — for example, @tsconfig/svelte for the Svelte configs or vite for the *-app configs.

Which config do I extend?

Pick by what you are building, not by framework alone. Every config is either a library (emits .d.ts) or an app (noEmit); the two are mutually exclusive, so each project uses one or the other.

| You are building | Extend | | ----------------------------------------------------------------------------------------- | ------------------ | | A framework-agnostic, runtime-agnostic library (e.g. a utility or React hook library) | generic-lib.json | | A React component library | react-lib.json | | A React single-page app | react-app.json | | A Vue component library | vue-lib.json | | A Vue single-page app | vue-app.json | | A Svelte component library | svelte-lib.json | | A Svelte single-page app | svelte-app.json | | A Bun service, CLI, or app (always run by Bun) | bun.json |

Notes:

• React hook libraries that are runtime-agnostic use generic-lib.json (it is DOM-free); a hook library that genuinely needs the browser is just a react-lib.json.

• Bun has no -lib/-app split: it never emits (Bun runs .ts directly), so services, CLIs, and published apps all share bun.json.

• Vue + Pug: compose the Pug mixin alongside your Vue config:

  {
  	"extends": [
  		"@gabegabegabe/tsconfig/vue-app.json",
  		"@gabegabegabe/tsconfig/vue-pug.json"
  	]
  }

Required project-level types

Because TypeScript 6.0 defaults types to [] (no automatic @types discovery), some configs assume you install the relevant types package:

• bun.json sets types: ["bun"] — install @types/bun.
• The *-app configs set types: ["vite/client"] — install vite.

Architecture

The configs are assembled from small composable layers via TypeScript's array extends. You normally extend a leaf config (above); the layers are the building blocks.

| Layer | Role | | --------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | opinions.json | Extends @tsconfig/strictest and adds universal preferences (erasableSyntaxOnly, moduleDetection: force, resolveJsonModule, noUncheckedSideEffectImports, allowJs: false). Composed last wherever an external base might relax strictness. | | base.json | DOM-free, emit-neutral foundation: target/module/lib/moduleResolution and friends. The root for non-Svelte, non-Bun configs. | | browser.json | Adds the DOM library (dom, dom.iterable). | | emit.json | The library emit set (declaration, isolatedDeclarations, stripInternal, …). |

Svelte and Bun configs build on their official upstream bases (@tsconfig/svelte, @tsconfig/bun) instead of base.json, composing opinions.json last so strictness wins.

Conventions

When adding or modifying configs, follow these rules:

• A config exists only for a distinct compiler environment. Distinct project roles that share an environment (e.g. hook library vs. utility library) are documented here, not given their own file.
• Defer structure to an official base where one exists (Svelte, Bun); only apply opinions on top, and always compose opinions.json last so @tsconfig/strictest overrides anything the upstream base relaxes.
• Be explicit about load-bearing options; rely on TypeScript defaults for nothing structural. Defaults are version-volatile (6.0 changed many), so pinning them is robustness. Do not, however, redeclare a value already set by a config earlier in the extends chain.
• lib arrays replace, never merge across extends, so browser.json restates esnext and must be composed after the base that sets lib.

Requirements

• TypeScript >=6.0 (uses erasableSyntaxOnly, isolatedDeclarations, array extends).
• @tsconfig/strictest (required).
• Optional, per config: @tsconfig/svelte (Svelte), @tsconfig/bun (Bun), @vue/language-plugin-pug (Vue + Pug), vite (*-app).

Development

Add or edit the .json files at the repository root. Use the TSConfig Documentation as a reference for available options.

Linting

ESLint lints the JSON config files. Run:

bun run lint