TypeScript Configuration Standard
This standard explains ownership and intent for tsconfig*.json files. The
TypeScript TSConfig reference
defines compiler option semantics. Meridian policy is to make project
boundaries and execution intent understandable without copying a universal
set of compiler options into every package.
TypeScript config files accept JSON with comments, so a compact reference may
be placed near the top when the file is edited:
// Public standard: https://agents.meridianstack.dev/standards/typescript-configuration
The reference points to this guidance; it does not make the explanatory text
part of the compiler configuration.
Inheritance and project ownership
Use extends to inherit shared defaults from a deliberate base configuration.
Keep each config's relative paths understandable from the file where they are
declared: TypeScript resolves inherited relative paths relative to their
originating config file. Child values can override inherited values, andfiles, include and exclude replace the corresponding inherited lists.
See the official extends reference.
The repository base config owns shared compiler defaults. A package owns its
source inclusion, output layout, references and target-specific options.
Package-local overrides are appropriate when the package has a distinct
runtime, emitted artifact, test boundary or editor/build role. Keep separate
build and test configs when their source sets or emit behaviour differ; avoid
copying the entire base configuration just to change a small number of
settings.
Runtime and project boundaries
Compiler settings must match the code's actual runtime and consumers. Browser,
Node.js, Worker and test environments can have different globals, module
resolution and emit requirements. Do not add runtime libraries to a shared
base merely because one package needs them.
Use TypeScript project references when independently buildable projects need
explicit dependency boundaries or faster incremental workflows. References
are not inherited through extends; declare them on the owning solution or
project config. They do not replace package dependency declarations or runtime
boundaries. See Project References.
exclude limits files discovered through include; it does not prevent a
file from entering a program through imports, explicit files, types or
reference directives. Keep exclusions aligned with the intended project
boundary rather than treating them as an access-control mechanism.
Exceptions and validation
Document non-obvious local overrides where future maintainers might otherwise
remove them. Prefer the narrowest config that expresses the real runtime or
build distinction. Validate with the package's configured typecheck and build
commands; a passing editor session is not a substitute for those checks.