External types in app.d.ts

[pzerelles]

Describe the bug

When I define an interface in app.d.ts that belongs to the App namespace, I want to use a type defined in another .ts file. I can import my type into app.d.ts, but when I use for example App.Locals in hooks, the type is not correctly identified in VSCode.

Reproduction

Create a new SvelteKit project with app.d.ts like this:

/// <reference types="@sveltejs/kit" />

// See https://kit.svelte.dev/docs#typescript
// for information about these interfaces
declare namespace App {
	import { User } from './routes/test';

	interface Locals {
		user: User;
	}

	interface Platform {}

	interface Session {}

	interface Stuff {}
}

and in routes a file test.ts with:

import type { RequestHandler } from '@sveltejs/kit';

export interface User {
	id: number;
}

export const get: RequestHandler = async ({ locals }) => {
	let { id } = locals.user;
	id = 'test';

	return {
		status: 200,
		body: id
	};
};

I expected an error, because id should be a number. But the type is not correctly identified in VSCode IDE.

Logs

No response

System Info

System:
    OS: macOS 12.2
    CPU: (16) x64 Intel(R) Core(TM) i9-9880H CPU @ 2.30GHz
    Memory: 7.76 GB / 32.00 GB
    Shell: 5.8 - /bin/zsh
  Binaries:
    Node: 14.17.3 - ~/n/bin/node
    Yarn: 1.22.11 - ~/n/bin/yarn
    npm: 7.20.0 - ~/n/bin/npm
  Browsers:
    Chrome: 98.0.4758.80
    Firefox: 96.0.2
    Safari: 15.3
  npmPackages:
    @sveltejs/adapter-auto: next => 1.0.0-next.17 
    @sveltejs/kit: next => 1.0.0-next.260 
    svelte: ^3.44.0 => 3.46.4

Severity

serious, but I can work around it

Additional Information

No response

[f-elix]

The App namespace is global. If you import (or export) something in app.d.ts, you're essentially turning the file into a ts module, which means all the types in that file have to be imported to be available. That's why Locals is no longer typed.

If you need custom types for the App namespace, you have to either declare them directly in the file, or declare them as global, like this:

Instead of:

export type User = {};

do:

declare global {
  type User = {};
}

You'll be able to use the User type anywhere in your app without importing it, including app.d.ts.

[JeanJPNM]

When you put an import inside a declaration file it turns into an es6 module (except when the import is under a module declaration), Thus the declaration of App stops being global and you are left with the default one.

To fix the issue simply wrap the namespace declaration with declare global like this:

/// <reference types="@sveltejs/kit" />

// See https://kit.svelte.dev/docs#typescript
// for information about these interfaces

import type { User } from './routes/foo';

declare global {
	declare namespace App {
		interface Locals {
			user: User;
		}

		interface Platform {}

		interface Session {}

		interface Stuff {}
	}
}

[MISTOM]

Thankyou for this

[pzerelles]

Both solutions work and give to different views on the problem. Thanks a lot for the help, @f-elix and @JeanJPNM!

[fehnomenal]

You can also do:

/// <reference types="@sveltejs/kit" />

declare namespace App {
  import type { BackgroundJobQueue } from 'backend-common';

  interface Locals {
    jobQueue: BackgroundJobQueue;
  }

  interface Platform {}

  interface Session {}

  interface Stuff {}
}

[xpat]

How are app.d.ts and $env module related? I'm using adapter-cloudflare and following this guide. There's a note that says:

SvelteKit's built-in $env module should be preferred for environment variables.

When and why and how would I use $env? If I create my sveltekit project with TypeScript (but not if I create it with JsDoc) I'm able to get a Cloudflare D1 database to return json using just the app.d.ts file.

// for information about these interfaces
declare global {
        namespace App {
                // interface Error {}
                // interface Locals {}
                // interface PageData {}
                   interface Platform {
      env: {
        DB: D1Database;
      };
      context: {
        waitUntil(promise: Promise<any>): void;
      };
      caches: Cache
        }
}

export {};

If I create a project with just javascript, there is no app.d.ts file. Is there a way to return json from the Cloudflare D1 without using TypeScript, or making it work with JsDoc? In there a case when $env would not only be preferred but the only option? When there is an app.d.ts file, can you and should you bypass it in favor of $env?