diff --git a/.changeset/selfish-tools-prove.md b/.changeset/selfish-tools-prove.md
new file mode 100644
index 0000000000000..b2f05672fe83e
--- /dev/null
+++ b/.changeset/selfish-tools-prove.md
@@ -0,0 +1,5 @@
+---
+'create-svelte': minor
+---
+
+fix: adjust `app.d.ts` to diminish confusion about imports
diff --git a/packages/create-svelte/templates/default/src/app.d.ts b/packages/create-svelte/templates/default/src/app.d.ts
index 26a9569bc40a0..c00544683c271 100644
--- a/packages/create-svelte/templates/default/src/app.d.ts
+++ b/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;
diff --git a/packages/create-svelte/templates/skeleton/src/app.d.ts b/packages/create-svelte/templates/skeleton/src/app.d.ts
index 26a9569bc40a0..c00544683c271 100644
--- a/packages/create-svelte/templates/skeleton/src/app.d.ts
+++ b/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;
diff --git a/packages/create-svelte/templates/skeletonlib/src/app.d.ts b/packages/create-svelte/templates/skeletonlib/src/app.d.ts
index b9091cd1c51da..c00544683c271 100644
--- a/packages/create-svelte/templates/skeletonlib/src/app.d.ts
+++ b/packages/create-svelte/templates/skeletonlib/src/app.d.ts
@@ -1,11 +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;
diff --git a/packages/kit/types/ambient.d.ts b/packages/kit/types/ambient.d.ts
index a8bd4cf9fc062..98fdede92b391 100644
--- a/packages/kit/types/ambient.d.ts
+++ b/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
- * ///
- *
- * 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 {
/**