Repository-wide TypeScript and style guidance for Toolkit. See the CLI guide and MCP guide for product-specific implementation patterns.
Every first-party TypeScript file is type-checked with TypeScript 7 (tsc
from the typescript catalog entry).
- Shared base. Every project extends the root
tsconfig.base.json. Its checking options apply everywhere. They includestrict,noUncheckedIndexedAccess,exactOptionalPropertyTypes,noPropertyAccessFromIndexSignature,verbatimModuleSyntax,erasableSyntaxOnly,noUnusedLocals,noUnusedParameters, andskipLibCheck: false. A project sets only its runtime:target,module,moduleResolution,lib,types, JSX, and emit. The codemod is the one exception:jssgcannot follow anextendsoutside its package, so its tsconfig repeats the checking options. - Don't weaken the policy.
scripts/tsconfig-policy.test.mjsruns in CI. It fails when a project overrides a policy option, when a tracked TypeScript file is in no checked program, or when a package that has atsconfig.jsonhas notypecheckscript. - Library-check exceptions. If a dependency's declarations fail and no
dependency fix exists, set
skipLibCheck: truein the affected program only. Add one comment line per dependency:// skipLibCheck exception: <dependency> <diagnostic>. Remove when <condition>. - Running the check.
pnpm run typecheckbuilds the workspace and runs every package'stypecheckscript;pnpm run tscis an alias. In a package, runpnpm run typecheck. CI runs each package's script throughpackage.json#sentryCi. If results look stale after a tsconfig change, delete the package'snode_modules/.tmpbuild info. - Optional properties. Under
exactOptionalPropertyTypes,x?: Tdoes not acceptundefined. Omit the key with a conditional spread, or withomitUndefined()in mcp-core. Declarex?: T | undefinedonly when callers forward a value that can be undefined, such as an optional zod field. - Compiler API. TypeScript 7 has no JavaScript compiler API. Code that
parses or prints TypeScript imports
@typescript/typescript6.tscstays on TypeScript 7. - Known exceptions.
apps/cli-docsrunsastro checkon TypeScript 6 (theastro-checkcatalog) until@astrojs/checksupports TypeScript 7.@sentry/mcp-coreemits declarations through tsdown's tsgo backend. - tsrs. Type-aware lint runs on
tsrs-lintfrom tsrs, a Rust port of the TypeScript compiler. Oxlint preferstsrs-lintovertsgolintwhen both are installed;.pnpmfile.cjsdrops oxlint's optionaloxlint-tsgolintpeer so only tsrs is present. tsrs implements TypeScript 7.1 beta, and it only backs lint:pnpm run typecheckstays on TypeScript 7.0 and decides type errors. Don't use tsrs--fastmode, which has reported false errors here. Don't useoxlint --type-checkas a substitute fortypecheckeither: it checks each file under one tsconfig, so it misses programs such as toolkit-core's browser build.
- 2 spaces, double quotes, semicolons
- Formatter width: 80 characters
- Trailing commas in multiline
- Root, MCP, and CLI files use Oxlint and Oxfmt. The CLI-specific rules live in
packages/cli/lint-rules/cli-oxlint-plugin.js, with inline Oxlint suppressions for intentional exceptions. - Write new lint rules for Oxlint: turn on a built-in rule in
.oxlintrc.json(for exampleno-restricted-imports), or add a custom rule to the Oxlint JS plugin above and register it in.oxlintrc.json. Do not add new ast-grep rules; the few left inast-grep-rules/predate this. - Oxlint runs type-aware (
options.typeAwarein.oxlintrc.json, backed bytsrs-lint).typescript/return-await(always) is on repo-wide: writereturn awaitin async functions so callers stay in async stack traces. - Repo-wide promise and error rules:
no-misused-promises,switch-exhaustiveness-check(adefaultbranch counts),only-throw-error,prefer-promise-reject-errors,no-base-to-string, andno-unsafe-enum-comparison. In the CLI, rethrow a caught value recorded earlier (for example by a callback) withrethrow()fromsrc/lib/rethrow.ts, so it reaches callers unchanged. - Non-test source outside the CLI also gets
no-explicit-any,no-non-null-assertion,no-unnecessary-condition, and theno-unsafe-*rules. Validate untrusted data (zod or a type guard) instead of reading it asany.packages/cli/srcalready bansanyand!. - Type-aware lint reads workspace packages through their built declarations.
Build them before linting, or imports read as error types:
pnpm --filter '@sentry/mcp-core...' --filter @sentry/logger run build. - Copy and combine iterables with spread:
[...set],[...a, ...b],[...path, key].unicorn/prefer-spreadenforces this repo-wide and autofixesArray.from(x)and.slice(). Spread rejects non-iterables at compile time and at runtime, whereArray.fromaccepts any{ length }object. KeepArray.fromfor array-likes andArray.from({ length: n }, fn). To walk a string's UTF-16 code units, usesplit(""). Spread a string only when you mean code points, and suppresstypescript/no-misused-spreadwith the reason. - Don't pass an async callback to
.catch(). Usetry/await/catch, or a wrapper such aswithDashboardErrors(ctx, fn). Theno-async-catch-callbackast-grep rule enforces this. - VS Code uses the Oxc extension for formatting and linting. Run
pnpm exec oxfmt --write <file>to format a file.
- Files:
kebab-case.ts - Functions:
camelCase - Types/Classes:
PascalCase - Constants:
UPPER_SNAKE_CASE
// 1. Node built-ins
import { readFile } from "node:fs/promises";
// 2. External deps
import { z } from "zod";
// 3. Internal packages
import { mockData } from "@sentry-mcp/mocks";
// 4. Relative imports
import { UserInputError } from "./errors.js";export const toolName = {
description: "Clear, concise description",
parameters: z.object({
required: z.string().describe("Description"),
optional: z.string().optional(),
}),
execute: async (params, context) => {
// 1. Validate inputs
// 2. Call API
// 3. Format output
return formatResponse(data);
},
};describe("Component", () => {
it("handles normal case", async () => {
// Arrange
const input = createTestInput();
// Act
const result = await method(input);
// Assert
expect(result).toMatchInlineSnapshot();
});
});Key practices:
- Use inline snapshots for formatting
- Mock with MSW
- Test success and error paths
- Keep tests isolated
Before committing:
pnpm -w run lint # Oxlint and ast-grep checks for root, MCP, and CLI
pnpm -w run lint:fix # Fix issues
pnpm -w run format # Format with Oxfmt
pnpm --filter sentry run lint # CLI-specific lint and format checks
pnpm -w run typecheck # Type check every package
pnpm test # Run tests
pnpm -w run build # Build all/**
* Brief description.
*
* @param param - Description
* @returns What it returns
*
* @example
* ```typescript
* const result = func(param);
* ```
*/- Never commit secrets
- Validate all inputs
- Use environment variables
- Sanitize displayed data
For shared patterns see:
- Error handling: common-patterns.md
- Zod schemas: common-patterns.md
- API usage: api-patterns.md
- Testing: ../testing/overview.md
# Workspace-wide (from root)
pnpm -w run lint
# Package-specific (from package dir)
pnpm test- Architecture: ../architecture/overview.md
- Testing guide: ../testing/overview.md
- API patterns: api-patterns.md
- Common patterns: common-patterns.md