@sister.software/tsconfig 9.2.0 → 10.0.0

package/README.md

@@ -1,6 +1,44 @@
 # `@sister.software/tsconfig`
 
-This package contains the TypeScript configuration used by Sister Software.
+The TypeScript configuration used by Sister Software. Three flavors, one shared base.
 
-While it is possible to use this configuration outside of our projects,
-you may find that it is not as useful as other popular configurations.
+While it is possible to use this configuration outside of our projects, you may find that it is not
+as useful as other popular configurations.
+
+## Usage
+
+```jsonc
+// A package that runs on Node.
+{ "extends": "@sister.software/tsconfig/node" }
+```
+
+```jsonc
+// A package that runs in a browser.
+{ "extends": "@sister.software/tsconfig/web" }
+```
+
+```jsonc
+// A package that is neither — pure logic with no runtime globals.
+{ "extends": "@sister.software/tsconfig" }
+```
+
+| Entry point | Adds to the base                                                  |
+| ----------- | ----------------------------------------------------------------- |
+| `.`         | nothing — strict, `nodenext`, `lib: ["ESNext"]`, no ambient types  |
+| `./node`    | `types: ["node"]`                                                  |
+| `./web`     | `lib: ["ESNext", "DOM", "DOM.Iterable"]`, `types: []`, `react-jsx` |
+
+Pick by what the code _runs on_, not by what builds it. A browser package whose build scripts use
+Node still extends `/web`; those scripts are excluded from the project.
+
+### Why `./web` sets `types: []`
+
+An absent `types` auto-includes every `@types` package in `node_modules`. In a monorepo that hands a
+browser package the whole tooling surface, so Node's globals resolve in code that will never see
+them. Empty means "nothing ambient" — add what you need explicitly.
+
+### Compatibility
+
+Subpath resolution for `extends` needs **TypeScript 5.0+**, which is when `extends` began resolving
+through a package's `exports` map. `main` still points at the neutral config, so older TypeScript
+resolves the bare specifier as it always did — it just cannot reach `/node` or `/web`.

package/node.json

@@ -0,0 +1,8 @@
+{
+	"$schema": "https://json.schemastore.org/tsconfig",
+	"extends": "./tsconfig.json",
+	"compilerOptions": {
+		// Node's globals (process, Buffer, node: builtins). Everything else is inherited.
+		"types": ["node"]
+	}
+}

package/package.json

@@ -1,10 +1,21 @@
 {
   "name": "@sister.software/tsconfig",
-  "version": "9.2.0",
+  "version": "10.0.0",
   "description": "Sister Software's base TypeScript configuration.",
   "license": "AGPL-3.0",
   "author": "teffen@sister.software",
   "main": "tsconfig.json",
+  "exports": {
+    "./package.json": "./package.json",
+    ".": "./tsconfig.json",
+    "./node": "./node.json",
+    "./web": "./web.json"
+  },
+  "files": [
+    "tsconfig.json",
+    "node.json",
+    "web.json"
+  ],
   "type": "module",
   "engines": {
     "node": ">=24.0"

package/tsconfig.json

@@ -8,7 +8,6 @@
 		"incremental": true,
 		"verbatimModuleSyntax": true,
 		"lib": ["ESNext"],
-		"types": ["node"],
 		"newLine": "lf",
 		"noFallthroughCasesInSwitch": true,
 		"outDir": "${configDir}/out",
@@ -27,8 +26,7 @@
 		"module": "nodenext",
 		"moduleResolution": "nodenext",
 		"allowImportingTsExtensions": true,
-		"rootDir": "${configDir}",
-		"jsx": "react-jsx"
+		"rootDir": "${configDir}"
 	},
 	"exclude": [
 		// ---

package/web.json

@@ -0,0 +1,12 @@
+{
+	"$schema": "https://json.schemastore.org/tsconfig",
+	"extends": "./tsconfig.json",
+	"compilerOptions": {
+		"lib": ["ESNext", "DOM", "DOM.Iterable"],
+		// Empty rather than absent: absent auto-includes every @types package in node_modules, which in a
+		// monorepo hands a browser package the whole tooling surface. Add what you need explicitly.
+		"types": [],
+		// Inert for a package with no .tsx — set here so a browser package that grows one needs no config change.
+		"jsx": "react-jsx"
+	}
+}