---
public-agent: true
id: typescript-configuration
title: TypeScript Configuration Standard
status: current
classification: public-agent-standard
safety: reviewed-public
---

# TypeScript Configuration Standard

This standard explains ownership and intent for `tsconfig*.json` files. The
[TypeScript TSConfig reference](https://www.typescriptlang.org/tsconfig/)
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:

```jsonc
// 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, and
`files`, `include` and `exclude` replace the corresponding inherited lists.
See the official [`extends` reference](https://www.typescriptlang.org/tsconfig/extends.html).

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](https://www.typescriptlang.org/docs/handbook/project-references.html).

`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.
