From b5e163bb3766a01bf018bba147586023823db904 Mon Sep 17 00:00:00 2001
From: Nic Polumeyv <162764842+Nic-Polumeyv@users.noreply.github.com>
Date: Tue, 21 Jul 2026 13:12:20 -0400
Subject: [PATCH] breaking: stop generating ambient.d.ts

---
 .changeset/remove-generated-ambient.md         |  5 +++++
 documentation/docs/98-reference/54-types.md    |  2 +-
 packages/kit/src/core/sync/sync.js             |  2 --
 packages/kit/src/core/sync/write_ambient.js    | 18 ------------------
 packages/kit/src/core/sync/write_env.js        |  2 +-
 packages/kit/src/core/sync/write_tsconfig.js   |  1 -
 .../kit/src/core/sync/write_tsconfig.spec.js   |  1 -
 7 files changed, 7 insertions(+), 24 deletions(-)
 create mode 100644 .changeset/remove-generated-ambient.md
 delete mode 100644 packages/kit/src/core/sync/write_ambient.js

diff --git a/.changeset/remove-generated-ambient.md b/.changeset/remove-generated-ambient.md
new file mode 100644
index 000000000000..2ca65615f774
--- /dev/null
+++ b/.changeset/remove-generated-ambient.md
@@ -0,0 +1,5 @@
+---
+'@sveltejs/kit': major
+---
+
+breaking: stop generating `ambient.d.ts`, the `@sveltejs/kit` types reference moved into `env.d.ts`
diff --git a/documentation/docs/98-reference/54-types.md b/documentation/docs/98-reference/54-types.md
index d1d311ff036b..7ca6e1004488 100644
--- a/documentation/docs/98-reference/54-types.md
+++ b/documentation/docs/98-reference/54-types.md
@@ -138,7 +138,7 @@ The generated `.svelte-kit/tsconfig.json` file contains a mixture of options. So
 		"rootDirs": ["..", "./types"]
 	},
 	"include": [
-		"ambient.d.ts",
+		"env.d.ts",
 		"non-ambient.d.ts",
 		"./types/**/$types.d.ts",
 		"../vite.config.js",
diff --git a/packages/kit/src/core/sync/sync.js b/packages/kit/src/core/sync/sync.js
index 0adf76e3c5ac..ea6c2587e66a 100644
--- a/packages/kit/src/core/sync/sync.js
+++ b/packages/kit/src/core/sync/sync.js
@@ -4,7 +4,6 @@ import create_manifest_data from './create_manifest_data/index.js';
 import { write_client_manifest } from './write_client_manifest.js';
 import { write_tsconfig } from './write_tsconfig.js';
 import { write_types, write_all_types } from './write_types/index.js';
-import { write_ambient } from './write_ambient.js';
 import { write_non_ambient } from './write_non_ambient.js';
 import { write_server } from './write_server.js';
 import {
@@ -21,7 +20,6 @@ import { write_env } from './write_env.js';
  */
 export function init(config, root) {
 	write_tsconfig(config.kit, root);
-	write_ambient(config.kit);
 }
 
 /**
diff --git a/packages/kit/src/core/sync/write_ambient.js b/packages/kit/src/core/sync/write_ambient.js
deleted file mode 100644
index fe459c296801..000000000000
--- a/packages/kit/src/core/sync/write_ambient.js
+++ /dev/null
@@ -1,18 +0,0 @@
-import path from 'node:path';
-import { GENERATED_COMMENT } from '../../constants.js';
-import { write_if_changed } from './utils.js';
-
-// TODO get rid of this, it's useless
-
-/**
- * Writes ambient declarations including types reference to @sveltejs/kit,
- * and the existing environment variables in process.env to
- * $env/static/private and $env/static/public
- * @param {import('types').ValidatedKitConfig} config
- */
-export function write_ambient(config) {
-	/** @type {string} */
-	const content = `${GENERATED_COMMENT}\n/// <reference types="@sveltejs/kit" />`;
-
-	write_if_changed(path.join(config.outDir, 'ambient.d.ts'), content);
-}
diff --git a/packages/kit/src/core/sync/write_env.js b/packages/kit/src/core/sync/write_env.js
index 1a6946a81982..6ad018524d29 100644
--- a/packages/kit/src/core/sync/write_env.js
+++ b/packages/kit/src/core/sync/write_env.js
@@ -15,7 +15,7 @@ const DOCS = '// See https://svelte.dev/docs/kit/environment-variables for more
  * @param {Record<string, EnvVarConfig<any>> | null} env_config
  */
 export function write_env(kit, entry, env_config) {
-	const content = [];
+	const content = ['/// <reference types="@sveltejs/kit" />'];
 	const out = path.join(kit.outDir, 'env.d.ts');
 
 	if (entry && env_config) {
diff --git a/packages/kit/src/core/sync/write_tsconfig.js b/packages/kit/src/core/sync/write_tsconfig.js
index 324a7f33690d..537d286ab07d 100644
--- a/packages/kit/src/core/sync/write_tsconfig.js
+++ b/packages/kit/src/core/sync/write_tsconfig.js
@@ -59,7 +59,6 @@ export function get_tsconfig(kit, cwd) {
 	const config_relative = (file) => posixify(path.relative(kit.outDir, file));
 
 	const include = new Set([
-		'ambient.d.ts', // careful: changing this name would be a breaking change, because it's referenced in the service-workers documentation
 		'env.d.ts',
 		'non-ambient.d.ts',
 		'./types/**/$types.d.ts',
diff --git a/packages/kit/src/core/sync/write_tsconfig.spec.js b/packages/kit/src/core/sync/write_tsconfig.spec.js
index 3234717dfecc..1f7dd59526b7 100644
--- a/packages/kit/src/core/sync/write_tsconfig.spec.js
+++ b/packages/kit/src/core/sync/write_tsconfig.spec.js
@@ -92,7 +92,6 @@ test('Creates tsconfig include from kit.files', () => {
 	const { include } = get_tsconfig(kit, '.');
 
 	expect(include).toEqual([
-		'ambient.d.ts',
 		'env.d.ts',
 		'non-ambient.d.ts',
 		'./types/**/$types.d.ts',