sv-utils: generate the supported Handle import for Kit 2

Open Beginner friendly
  • Is something wrong?
#1,404 1 comment 0 reactions 0 assignees View on GitHub

Maintainers usually reply within 4 days

Nobody has claimed this yet.

Assessment

Difficulty
2/5
Estimated time
1-3 hours
Newbie friendliness
85/100
Issue type
Bug
Clarity
Clearly specified
Activity status
Active
Tech stack
typescript
Domain
cli, tooling

Research direction

Start in packages/sv-utils/src/tooling/js/kit.ts at addHooksHandle and inspect both the TypeScript import and JSDoc annotations it generates. Run the project's normal check, or the minimized type check described in the issue, across the supported Kit majors; done means the generated hook uses a valid Handle export and both forms type-check.

Written by the indexing model from the issue text.

Description

pkg:add

Summary

Adding Better Auth to a supported SvelteKit 2 project emits Handle imports from @sveltejs/kit/hooks. Kit 2 declares that type in @sveltejs/kit and does not export it from the hooks module. The generated hook fails type checking independently of the default Kit 3/Better Auth peer conflict.

Steps to reproduce

Start with a working TypeScript SvelteKit 2.70.3 project and use sv 1.0.1 to add the integrations:

npx --yes [email protected] add drizzle=database:sqlite+client:libsql better-auth=demo:password --no-install --no-git-check

Inspect src/hooks.server.ts. The generated import is:

import type { Handle } from '@sveltejs/kit/hooks';

Run the project's normal check. A minimized type check with the published Kit 2.70.3 declarations and TypeScript 6.0.3 also reproduces the error using only this import and export type ConsumerHandle = Handle.

Expected behavior

The hook generator uses the type export provided by the installed Kit major. Kit 2 projects remain supported by the add-on's setup contract and generated hook imports type-check.

Actual behavior

TypeScript reports:

TS2459: Module '"@sveltejs/kit/hooks"' declares 'Handle' locally, but it is not exported.

Changing only the type import to @sveltejs/kit removes that diagnostic. The minimized type check exits 2 before the correction and 0 afterward.

Affected area

packages/sv-utils/src/tooling/js/kit.ts, specifically addHooksHandle, used by the Better Auth add-on. The helper also writes the hooks-module import in JSDoc annotations.

Runtime or environment

sv 1.0.1, SvelteKit 2.70.3, TypeScript 6.0.3, Better Auth 1.7.7, Svelte 5.57.1, Node.js 22.23.2, npm 12.0.2 on macOS ARM64.

Evidence

Current helper at revision 7ff52c0955e1f07b8719029d60afac1ee634ad69 always sources Handle from @sveltejs/kit/hooks. Kit 2.70.3 type declarations import Handle locally in that module but do not export it. An isolated check against those exact declarations confirms the failing and corrected imports.

Impact

Using a Kit 2 dependency graph to satisfy Better Auth's peer requirements still leaves an independently invalid generated hook. The regression condition is that the helper's output type-checks for each supported Kit major, including its TypeScript and JSDoc forms.

Dominant language
TypeScript
Stars
513
Forks
110
Avg merge
5d 1h
Merged PRs (30d)
24

Getting set up

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.

More from sveltejs/cli

All issues in sveltejs/cli

Similar issues

More TypeScript issues

Get new issues in your inbox

A short digest of beginner-friendly GitHub issues.