Verified against @stacksjs/stx at 0.2.153 (local build of main, HEAD 0dcb6fbd0e).
TL;DR
useCookie is in the auto-import list, so a <script client> block can call it as a bare global — but it has no ambient declaration, unlike every other entry in that list. Correct code fails to type-check.
Evidence
In the auto-import list — packages/stx/src/client-script.ts:322:
'useLocalStorage', 'useSessionStorage', 'useCookie',Ambient declarations for these globals live in packages/stx/stx.d.ts (copied verbatim to dist/stx.d.ts), which declares useLocalStorage, useSessionStorage, useSearchParams, navigate, useColorMode and the rest. It declares useCookie zero times:
$ grep -c 'declare function useCookie' packages/stx/stx.d.ts
0Why it matters
The composable works at runtime. The only thing missing is the type, so the failure lands entirely on correct code:
// <script client>
const token = useCookie('session', { maxAge: 2592000, sameSite: 'Lax' })
// ^^^^^^^^^ TS2304: Cannot find name 'useCookie'.An app either suppresses the error or hand-writes a local declaration — and a local ambient declaration for a symbol upstream later declares does not collide, it merges, so a stale local copy silently widens the real shape with no diagnostic.
One more wrinkle worth capturing in the same fix
useCookie appears to be the only entry in STX_AUTO_IMPORTS that is not also assigned as a bare property on window; it is reachable at window.stx.useCookie. That distinction does not matter inside a <script client> block, which gets the auto-import destructuring, but it does in a store module (storesDir) — store bundles are injected raw with no auto-import pass, so a bare useCookie(...) there is a ReferenceError while useLocalStorage(...) beside it works. Reaching it as window.stx.useCookie is the workaround.
If the declaration is added, it would be worth having it reflect that reachability difference, or making the assignment uniform with the rest of the list.
Suggested fix
Add a declaration to packages/stx/stx.d.ts matching the composable at packages/stx/src/composables/use-cookie.ts, returning the signal shape the runtime template produces rather than the module composable's CookieRef — the two already differ, which is #1710.
Related
- #1710 — two
useCookieimplementations that diverge - #1707 —
CookieOptionsshadowed by an unrelated re-export
Both are about which useCookie you get; this one is about there being no declaration at all for the auto-imported global. Filed alongside two other declaration/implementation mismatches (navigate, useSearchParams).