sveltejs / sveltejs/kit

Route files’ type imports don’t work when imported via JSDoc `@import`

Open
#14,609 0 comments 0 reactions 0 assignees View on GitHub

Nobody has claimed this yet.

types / typescript
Dominant language
JavaScript
Stars
20.8k
Forks
2.3k
Avg merge
1d 16h
Merged PRs (30d)
156

Description

Describe the bug

In a project that uses JavaScript with JSDoc type annotations, the following works:

/** @type {import('./$types.d.ts').PageServerLoad} */
export async function load({ params }) {

But if you want to put the import at the top of the file with all your other imports, using JSDoc @import:

/** @import { PageServerLoad } from './$types.d.ts' */

/** @type {PageServerLoad} */
export async function load({ params }) {

You get a type error:

The return type of an async function or method must be the global Promise<T> type. ts(1065)
index.d.ts(1512, 63): The return type of an async function or method must be the global Promise<T> type. Did you mean to write Promise<OutputData>?

Reproduction

https://stackblitz.com/edit/sveltejs-kit-template-default-sbdxvh1e?file=README.md

To reproduce, run npm run check.

See how routes/+page.js errors but routes/about/+page.js does not.

Logs

System Info
System:
    OS: macOS 15.6.1
    CPU: (16) arm64 Apple M4 Max
    Memory: 640.02 MB / 64.00 GB
    Shell: 5.9 - /usr/local/bin/zsh
  Binaries:
    Node: 24.9.0 - /usr/local/bin/node
    Yarn: 1.22.22 - /opt/homebrew/bin/yarn
    npm: 11.6.0 - /usr/local/bin/npm
  Browsers:
    Chrome: 141.0.7390.54
    Chrome Canary: 143.0.7454.0
    Edge: 141.0.3537.57
    Firefox: 140.0.2
    Firefox Developer Edition: 141.0
    Safari: 18.6
  npmPackages:
    @sveltejs/adapter-node: ^5.3.1 => 5.3.1 
    @sveltejs/kit: ^2.37.0 => 2.37.0 
    @sveltejs/svelte-json-tree: ^2.2.1 => 2.2.1 
    @sveltejs/vite-plugin-svelte: ^6.1.3 => 6.1.3 
    svelte: ^5.16.0 => 5.38.2 
    vite: ^7.1.3 => 7.1.9
Severity

annoyance

Additional Information

No response

Contributor guide

Open the contributing guide

First steps

  1. Read the whole issue, then the project's contributing guide.
  2. Comment on the issue to say you are picking it up — it saves two people doing the same work.
  3. Fork the repository and make your change on a branch.
  4. Open a pull request that references the issue number.

Research direction

Start with the StackBlitz reproduction and compare routes/+page.js with routes/about/+page.js, where the two JSDoc import forms behave differently. Run npm run check while tracing the route type handling; done means the top-level JSDoc @import form type-checks without the reported Promise error.

Written by the indexing model from the issue text.

Assessment

Tech stack
javascript
Domain
frontend, web-dev
Issue type
Bug
Difficulty
3/5
Estimated time
1-2 days
Activity status
Stale
Clarity
Mostly clear
Newbie friendliness
45/100

Get new issues in your inbox

A short digest of beginner-friendly GitHub issues.