Presets

The three presets on one base, what each changes, and how to choose by what your type-check reaches.

@workspace/typescript-config 1.0.0Developmentunreleased, maintained in Foundation as a copy

`extends`	For
`@workspace/typescript-config/nodejs.json`	Node.js code with no browser surface: servers, tooling, scripts
`@workspace/typescript-config/react-library.json`	code whose type-check reaches `.tsx` files or DOM types, directly or through a dependency
`@workspace/typescript-config/nextjs.json`	a Next.js application

base.json is the root the three presets extend. Do not extend it yourself.

What each preset changes#

Setting	`base.json`	`nodejs.json`	`react-library.json`	`nextjs.json`
`lib`	`es2022`, `esnext.temporal`, `DOM`, `DOM.Iterable`	`es2022`, `esnext.temporal`	from base	from base
`types`	not set	`["node"]`	not set	not set
`jsx`	not set	not set	`react-jsx`	`preserve`
`noEmit`	not set	`true`	not set	`true`
`allowJs`	not set	not set	not set	`true`
`plugins`	not set	not set	not set	`[{"name": "next"}]`

What each setting means in practice:

nodejs.json has no DOM: document or window is an error (TS2584: Cannot find name 'document'). It loads the Node types, so it needs @types/node.
react-library.json compiles JSX with the automatic runtime: no import React per file. It does not set noEmit; run it as tsc --noEmit, or set outDir when the package does emit.
nextjs.json hands JSX to Next.js unchanged, allows .js files, and never emits. Its next plugin adds Next's checks in the editor; tsc on the command line ignores it.

With TypeScript 6, a preset that does not set types loads no global type packages: Node's process is unknown in a react-library.json package until you add "types": ["node"].

Choosing a preset#

Packages in a workspace are used from source. When your package imports another package, your type-check reads that package's .ts and .tsx files under your settings. So the question is not whether your package contains React, but what its type-check reaches:

Your package or app	Preset
a Next.js application	`nextjs.json`
reaches a `.tsx` file or DOM types, in its own files or a dependency's	`react-library.json`
a React application without Next (for example Vite)	`react-library.json`
neither	`nodejs.json`

A Node package that imports a component library fails under nodejs.json, although it has no JSX of its own:

Text

error TS6142: Module 'widgets/greeting' was resolved to '…/widgets/src/greeting.tsx', but '--jsx' is not set.

Under react-library.json the same package type-checks. ESLint chooses the other way round, by your own files only; see eslint-config.

Examples#

A React library that emits nothing:

JSON

{  "extends": "@workspace/typescript-config/react-library.json",  "include": ["src"],  "exclude": ["node_modules", "dist"]}

A Next.js application. Next creates next-env.d.ts; include it, with the types Next generates under .next/types:

JSON

{  "extends": "@workspace/typescript-config/nextjs.json",  "compilerOptions": {    "paths": {      "@/*": ["./*"]    },    "plugins": [{"name": "next"}]  },  "include": ["next-env.d.ts", "**/*.ts", "**/*.tsx", ".next/types/**/*.ts"],  "exclude": ["node_modules", ".next"]}

The example restates the next plugin because a plugins of your own replaces the inherited one; see Extending.

This page as Markdown