fix: adjust app.d.ts to diminish confusion about imports

closes #8276

.changeset/selfish-tools-prove.md

@@ -0,0 +1,5 @@
+---
+'create-svelte': minor
+---
+
+fix: adjust `app.d.ts` to diminish confusion about imports

packages/create-svelte/templates/default/src/app.d.ts

@@ -1,9 +1,15 @@
 // See https://kit.svelte.dev/docs/types#app
 // for information about these interfaces
 // and what to do when importing types
-declare namespace App {
-	// interface Error {}
-	// interface Locals {}
-	// interface PageData {}
-	// interface Platform {}
+declare global {
+	namespace App {
+		// interface Error {}
+		// interface Locals {}
+		// interface PageData {}
+		// interface Platform {}
+	}
 }
+
+// this line ensure this file is treated as a module.
+// It can be removed if you add an import to this file.
+export default undefined;

packages/create-svelte/templates/skeleton/src/app.d.ts

@@ -1,9 +1,15 @@
 // See https://kit.svelte.dev/docs/types#app
 // for information about these interfaces
 // and what to do when importing types
-declare namespace App {
-	// interface Error {}
-	// interface Locals {}
-	// interface PageData {}
-	// interface Platform {}
+declare global {
+	namespace App {
+		// interface Error {}
+		// interface Locals {}
+		// interface PageData {}
+		// interface Platform {}
+	}
 }
+
+// this line ensure this file is treated as a module.
+// It can be removed if you add an import to this file.
+export default undefined;

packages/create-svelte/templates/skeletonlib/src/app.d.ts

@@ -1,11 +1,15 @@
-/// <reference types="@sveltejs/kit" />
-
 // See https://kit.svelte.dev/docs/types#app
 // for information about these interfaces
 // and what to do when importing types
-declare namespace App {
-	// interface Error {}
-	// interface Locals {}
-	// interface PageData {}
-	// interface Platform {}
+declare global {
+	namespace App {
+		// interface Error {}
+		// interface Locals {}
+		// interface PageData {}
+		// interface Platform {}
+	}
 }
+
+// this line ensure this file is treated as a module.
+// It can be removed if you add an import to this file.
+export default undefined;

packages/kit/types/ambient.d.ts

@@ -2,41 +2,26 @@
  * It's possible to tell SvelteKit how to type objects inside your app by declaring the `App` namespace. By default, a new project will have a file called `src/app.d.ts` containing the following:
  *
  * ```ts
- * /// <reference types="@sveltejs/kit" />
- *
- * declare namespace App {
- * 	interface Error {}
- * 	interface Locals {}
- * 	interface PageData {}
- * 	interface Platform {}
- * }
- * ```
- *
- * By populating these interfaces, you will gain type safety when using `event.locals`, `event.platform`, and `data` from `load` functions.
- *
- * Note that since it's an ambient declaration file, you have to be careful when using `import` statements. Once you add an `import`
- * at the top level, the declaration file is no longer considered ambient and you lose access to these typings in other files.
- * To avoid this, either use the `import(...)` function:
- *
- * ```ts
- * interface Locals {
- * 	user: import('$lib/types').User;
- * }
- * ```
- * Or wrap the namespace with `declare global`:
- * ```ts
- * import { User } from '$lib/types';
- *
  * declare global {
  * 	namespace App {
- * 		interface Locals {
- * 			user: User;
- * 		}
- * 		// ...
+ * 		// interface Error {}
+ * 		// interface Locals {}
+ * 		// interface PageData {}
+ * 		// interface Platform {}
  * 	}
  * }
+ *
+ * export default undefined;
  * ```
  *
+ * By populating these interfaces, you will gain type safety when using `event.locals`, `event.platform`, and `data` from `load` functions.
+ *
+ * Note that since it's a declaration file, you have to be careful when using `import` statements. Once you add an `import`
+ * at the top level, the declaration file is no longer considered ambient, at which point you need to wrap `App` inside `declare global`
+ * to still be available throughout the app. Opposite to that is the behavior when there's no `import`, at which point having `declare global`
+ * _prevents_ the `App` types from being available.
+ * To safe you the headache of converting between the two this we provide a dummy `export` to force the file being a module.
+ * Do not remove it unless you have an `import` statement at the top level.
  */
 declare namespace App {
 	/**