breaking: overhaul tsconfig

.changeset/fresh-pots-smoke.md

@@ -0,0 +1,5 @@
+---
+'@sveltejs/kit': major
+---
+
+breaking: write tsconfig to `node_modules/$app/tsconfig`

.changeset/moody-bags-heal.md

@@ -0,0 +1,5 @@
+---
+'@sveltejs/kit': minor
+---
+
+feat: `$app/service-worker` module

.changeset/plain-jobs-flash.md

@@ -0,0 +1,5 @@
+---
+'@sveltejs/kit': minor
+---
+
+feat: better tsconfig validation

documentation/docs/10-getting-started/30-project-structure.md

@@ -13,11 +13,13 @@ my-project/
 │ │ └ [your param matchers]
 │ ├ routes/
 │ │ └ [your routes]
+│ ├ service-worker/
+│ │ ├ index.js
+│ │ └ tsconfig.json
 │ ├ app.html
 │ ├ error.html
 │ ├ hooks.client.js
 │ ├ hooks.server.js
-│ ├ service-worker.js
 │ └ instrumentation.server.js
 ├ static/
 │ └ [your static assets]
@@ -52,7 +54,7 @@ The `src` directory contains the meat of your project. Everything except `src/ro
   - `%sveltekit.error.message%` — the error message
 - `hooks.client.js` contains your client [hooks](hooks)
 - `hooks.server.js` contains your server [hooks](hooks)
-- `service-worker.js` contains your [service worker](service-workers)
+- `service-worker` contains your [service worker](service-workers)
 - `instrumentation.server.js` contains your [observability](observability) setup and instrumentation code
   - Requires adapter support. If your adapter supports it, it is guaranteed to run prior to loading and running your application code.
 

documentation/docs/98-reference/20-$app-service-worker.md

@@ -0,0 +1,7 @@
+---
+title: $app/service-worker
+---
+
+This module can only be imported in service workers.
+
+> MODULE: $app/service-worker

documentation/docs/98-reference/20-$app-tsconfig-service-worker.md

@@ -0,0 +1,14 @@
+---
+title: $app/tsconfig/service-worker
+---
+
+This module contains TypeScript configuration tailored for your service worker:
+
+```json
+/// file: src/service-worker/tsconfig.json
+{
+	"extends": "$app/tsconfig/service-worker"
+}
+```
+
+You can extend this configuration with your own `compilerOptions`, adhering to the same restrictions as [`$app/tsconfig`]($app-tsconfig).

documentation/docs/98-reference/20-$app-tsconfig.md

@@ -0,0 +1,23 @@
+---
+title: $app/tsconfig
+---
+
+This module contains TypeScript configuration tailored for your app. Your own config should extend it — a typical `tsconfig.json` looks like this:
+
+```json
+/// file: tsconfig.json
+{
+	"extends": "$app/tsconfig",
+	"includes": ["src", "test"],
+	"excludes": ["src/service-worker"]
+}
+```
+
+You can extend this configuration with your own `compilerOptions`. Overriding the following properties may cause things to break — SvelteKit will warn you if this happens:
+
+- `paths` — this is derived from the (deprecated) [`alias`](configuration#alias) config option, together with any [subpath imports](https://nodejs.org/api/packages.html#subpath-imports) specified in your `package.json`, to align behaviour between Vite and TypeScript. Ideally, configure subpath imports rather than using `paths` directly
+- `types` — your app needs to be able to 'see' generated module declarations for things like [environment variables](environment-variables), and as such this array must include `"$app/types"`
+- `isolatedModules` — must be `true`, as Vite compiles modules one at a time
+- `verbatimModuleSyntax` — must be `true`, so that you can safely use type imports in `.svelte` files
+
+Note that the example configuration above excludes `src/service-worker`, because service workers need to be in their own TypeScript project. If you are using a service worker, create a `src/service-worker/tsconfig.json` that extends [`$app/tsconfig/service-worker`]($app-tsconfig-service-worker).

documentation/docs/98-reference/54-types.md

@@ -119,80 +119,9 @@ Starting with version 2.16.0, two additional helper types are provided: `PagePro
 > </script>
 > ```
 
-> [!NOTE] For this to work, your own `tsconfig.json` or `jsconfig.json` should extend from the generated `.svelte-kit/tsconfig.json` (where `.svelte-kit` is your [`outDir`](configuration#outDir)):
+> [!NOTE] For this to work, your own `tsconfig.json` or `jsconfig.json` should extend from the generated `$app/types`:
 >
-> `{ "extends": "./.svelte-kit/tsconfig.json" }`
-
-### Default tsconfig.json
-
-The generated `.svelte-kit/tsconfig.json` file contains a mixture of options. Some are generated programmatically based on your project configuration, and should generally not be overridden without good reason:
-
-```json
-/// file: .svelte-kit/tsconfig.json
-{
-	"compilerOptions": {
-		"paths": {
-			"#lib": ["../src/lib/index.js"],
-			"#lib/*": ["../src/lib/*"]
-		},
-		"rootDirs": ["..", "./types"]
-	},
-	"include": [
-		"ambient.d.ts",
-		"non-ambient.d.ts",
-		"./types/**/$types.d.ts",
-		"../vite.config.js",
-		"../vite.config.ts",
-		"../src/**/*.js",
-		"../src/**/*.ts",
-		"../src/**/*.svelte",
-		"../tests/**/*.js",
-		"../tests/**/*.ts",
-		"../tests/**/*.svelte"
-	],
-	"exclude": [
-		"../node_modules/**",
-		"../src/service-worker.js",
-		"../src/service-worker/**/*.js",
-		"../src/service-worker.ts",
-		"../src/service-worker/**/*.ts",
-		"../src/service-worker.d.ts",
-		"../src/service-worker/**/*.d.ts"
-	]
-}
-```
-
-Others are required for SvelteKit to work properly, and should also be left untouched unless you know what you're doing:
-
-```json
-/// file: .svelte-kit/tsconfig.json
-{
-	"compilerOptions": {
-		// this ensures that types are explicitly
-		// imported with `import type`, which is
-		// necessary as Svelte/Vite cannot
-		// otherwise compile components correctly
-		"verbatimModuleSyntax": true,
-
-		// Vite compiles one TypeScript module
-		// at a time, rather than compiling
-		// the entire module graph
-		"isolatedModules": true,
-
-		// Tell TS it's used only for type-checking
-		"noEmit": true,
-
-		// This ensures both `vite build`
-		// and `svelte-package` work correctly
-		"lib": ["esnext", "DOM", "DOM.Iterable"],
-		"moduleResolution": "bundler",
-		"module": "esnext",
-		"target": "esnext"
-	}
-}
-```
-
-Use the [`typescript.config` setting](configuration#typescript) of the SvelteKit plugin in `vite.config.js` to extend or modify the generated `tsconfig.json`.
+> `{ "extends": "$app/tsconfig" }`
 
 ## app.d.ts
 

eslint.config.js

@@ -45,7 +45,9 @@ export default [
 	{
 		languageOptions: {
 			parserOptions: {
-				projectService: true
+				projectService: {
+					allowDefaultProject: ['packages/kit/src/runtime/app/service-worker/index.js']
+				}
 			}
 		},
 		rules: {

packages/adapter-cloudflare/test/apps/pages/tsconfig.json

@@ -9,5 +9,5 @@
 		"sourceMap": true,
 		"moduleResolution": "bundler"
 	},
-	"extends": "./.svelte-kit/tsconfig.json"
+	"extends": "$app/tsconfig"
 }

packages/adapter-cloudflare/test/apps/workers/tsconfig.json

@@ -9,5 +9,5 @@
 		"sourceMap": true,
 		"moduleResolution": "bundler"
 	},
-	"extends": "./.svelte-kit/tsconfig.json"
+	"extends": "$app/tsconfig"
 }

packages/adapter-netlify/test/apps/basic/tsconfig.json

@@ -9,5 +9,5 @@
 		"sourceMap": true,
 		"moduleResolution": "bundler"
 	},
-	"extends": "./.svelte-kit/tsconfig.json"
+	"extends": "$app/tsconfig"
 }

packages/adapter-netlify/test/apps/edge/tsconfig.json

@@ -9,5 +9,5 @@
 		"sourceMap": true,
 		"moduleResolution": "bundler"
 	},
-	"extends": "./.svelte-kit/tsconfig.json"
+	"extends": "$app/tsconfig"
 }

packages/adapter-netlify/test/apps/instrumentation/tsconfig.json

@@ -10,5 +10,5 @@
 		"strict": true,
 		"moduleResolution": "bundler"
 	},
-	"extends": "./.svelte-kit/tsconfig.json"
+	"extends": "$app/tsconfig"
 }

packages/adapter-netlify/test/apps/split/tsconfig.json

@@ -9,5 +9,5 @@
 		"sourceMap": true,
 		"moduleResolution": "bundler"
 	},
-	"extends": "./.svelte-kit/tsconfig.json"
+	"extends": "$app/tsconfig"
 }

packages/adapter-node/test/apps/basic/tsconfig.json

@@ -9,5 +9,5 @@
 		"sourceMap": true,
 		"moduleResolution": "bundler"
 	},
-	"extends": "./.svelte-kit/tsconfig.json"
+	"extends": "$app/tsconfig"
 }

packages/adapter-static/test/apps/spa/jsconfig.json

@@ -1,4 +1,4 @@
 {
-	"extends": "./.svelte-kit/tsconfig.json",
+	"extends": "$app/tsconfig",
 	"include": ["src/**/*.d.ts", "src/**/*.js", "src/**/*.svelte"]
 }

packages/adapter-vercel/test/apps/basic/tsconfig.json

@@ -1,5 +1,5 @@
 {
-	"extends": "./.svelte-kit/tsconfig.json",
+	"extends": "$app/tsconfig",
 	"compilerOptions": {
 		"rewriteRelativeImportExtensions": true,
 		"allowJs": true,

packages/enhanced-img/test/apps/basics/jsconfig.json

@@ -1,4 +1,4 @@
 {
-	"extends": "./.svelte-kit/tsconfig.json",
+	"extends": "$app/tsconfig",
 	"include": ["src/**/*.d.ts", "src/**/*.js", "src/**/*.svelte", "*.js", "test/*.js"]
 }

packages/kit/scripts/generate-dts.js

@@ -1,5 +1,5 @@
 import { createBundle } from 'dts-buddy';
-import { readFileSync } from 'node:fs';
+import { readFileSync, writeFileSync } from 'node:fs';
 
 await createBundle({
 	output: 'types/index.d.ts',
@@ -14,6 +14,7 @@ await createBundle({
 		'$app/navigation': 'src/runtime/app/navigation.js',
 		'$app/paths': 'src/runtime/app/paths/public.d.ts',
 		'$app/server': 'src/runtime/app/server/index.js',
+		'$app/service-worker': 'src/runtime/app/service-worker/index.js',
 		'$app/state': 'src/runtime/app/state/index.js'
 	},
 	include: ['src'],
@@ -24,10 +25,19 @@ await createBundle({
 });
 
 // dts-buddy doesn't inline imports of module declaration in ambient-private.d.ts but also doesn't include them, resulting in broken types - guard against that
-const types = readFileSync('./types/index.d.ts', 'utf-8');
+let types = readFileSync('types/index.d.ts', 'utf-8');
+
 if (types.includes('__sveltekit/')) {
 	throw new Error(
 		'Found __sveltekit/ in types/index.d.ts - make sure to hide internal modules by not just reexporting them. Contents:\n\n' +
 			types
 	);
 }
+
+// this line causes type-checking to fail — simplest fix is to ignore it
+types = types.replace(
+	'export const self: ServiceWorkerGlobalScope;',
+	'// @ts-ignore\n\texport const self: ServiceWorkerGlobalScope;'
+);
+
+writeFileSync('types/index.d.ts', types);

packages/kit/src/cli.js

@@ -75,19 +75,19 @@ if (!command) {
 }
 
 if (command === 'sync') {
-	// create placeholder .svelte-kit/tsconfig.json if necessary, to squelch warnings.
+	// create placeholder node_modules/$app/tsconfig/tsconfig.json if necessary, to squelch warnings.
 	// this isn't bulletproof — if someone has some esoteric config, it will continue
 	// to harmlessly warn — but we handle the 90% case and clean up after ourselves
-	const sveltekit_dir = '.svelte-kit';
-	const base_tsconfig = `${sveltekit_dir}/tsconfig.json`;
+	const dir = 'node_modules/$app/tsconfig';
+	const base_tsconfig = `${dir}/tsconfig.json`;
 	const base_tsconfig_json = '{}';
 
-	const sveltekit_dir_exists = fs.existsSync(sveltekit_dir);
+	const sveltekit_dir_exists = fs.existsSync(dir);
 	const base_tsconfig_exists = fs.existsSync(base_tsconfig);
 
 	if (!base_tsconfig_exists) {
 		try {
-			fs.mkdirSync('.svelte-kit');
+			fs.mkdirSync(dir, { recursive: true });
 		} catch {
 			// ignore
 		}
@@ -100,7 +100,7 @@ if (command === 'sync') {
 		const sveltekit_config = extract_svelte_config(vite_config);
 
 		const sync = await import('./core/sync/sync.js');
-		sync.all_types(sveltekit_config);
+		sync.all_types(sveltekit_config, vite_config.root);
 
 		const explicit_env_entry = resolve_explicit_env_entry(sveltekit_config.kit);
 		await sync.env(sveltekit_config.kit, explicit_env_entry, vite_config.root, values.mode);
@@ -113,8 +113,8 @@ if (command === 'sync') {
 			fs.unlinkSync(base_tsconfig);
 		}
 
-		if (!sveltekit_dir_exists && fs.readdirSync(sveltekit_dir).length === 0) {
-			fs.rmSync(sveltekit_dir, { recursive: true });
+		if (!sveltekit_dir_exists && fs.readdirSync(dir).length === 0) {
+			fs.rmSync(dir, { recursive: true });
 		}
 	}
 } else {

packages/kit/src/constants.js

@@ -4,7 +4,7 @@
  */
 export const SVELTE_KIT_ASSETS = '/_svelte_kit_assets';
 
-export const GENERATED_COMMENT = '// this file is generated — do not edit it\n';
+export const GENERATED_COMMENT = '// this file is generated — do not edit it';
 
 export const ENDPOINT_METHODS = ['GET', 'POST', 'PUT', 'PATCH', 'DELETE', 'OPTIONS', 'HEAD'];
 

packages/kit/src/core/config/options.js

@@ -286,9 +286,14 @@ export const validate_kit_options = object({
 		server: boolean(false)
 	}),
 
-	typescript: object({
-		config: fun((config) => config)
-	}),
+	typescript: deprecate(
+		object({
+			config: fun((config) => config)
+		}),
+		(keypath) => {
+			return `The \`${keypath}\` option is deprecated, and will be removed in a future version. Add configuration to tsconfig.json directly`;
+		}
+	),
 
 	version: object({
 		name: string(Date.now().toString()),