Route files’ type imports don’t work when imported via JSDoc `@import`
Nobody has claimed this yet.
- 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 globalPromise<T>type. Did you mean to writePromise<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
First steps
- Read the whole issue, then the project's contributing guide.
- Comment on the issue to say you are picking it up — it saves two people doing the same work.
- Fork the repository and make your change on a branch.
- 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