Skip to content

feat: ship type declarations for @webjsdev/server (fix TS7016) - #322

Merged
vivek7405 merged 3 commits into
mainfrom
feat/server-type-declarations
Jun 3, 2026
Merged

feat: ship type declarations for @webjsdev/server (fix TS7016)#322
vivek7405 merged 3 commits into
mainfrom
feat/server-type-declarations

Conversation

@vivek7405

Copy link
Copy Markdown
Collaborator

Closes #310

Summary

@webjsdev/core shipped an index.d.ts + a types export condition, but @webjsdev/server shipped neither. So under strict + nodenext a TypeScript app's import { createRequestHandler, cors, cache, createAuth, rateLimit, sitemap, ... } from '@webjsdev/server' emitted TS7016 ("Could not find a declaration file for module"). That blocked the webjs typecheck-in-CI story (a fresh scaffold would fail on the server import) and left a core import untyped for every TS app.

This ships a hand-authored, types-only overlay (the runtime stays plain .js + JSDoc, zero runtime cost):

  • packages/server/index.d.ts types every named export of index.js. The high-traffic public API is precisely typed from each source's JSDoc (createRequestHandler return shape, cache<T> preserving the wrapped signature + .invalidate(), cors/rateLimit returning Middleware, sitemap/sitemapIndex returning string, Session, the revalidate* family, the context helpers, the cache stores, createAuth/Credentials/Google/GitHub). It reuses core's PageProps/LayoutProps/RouteHandlerContext rather than redefining, and defines ActionResult<T> locally (core does not export it) matching the documented envelope. Lower-traffic internals get reasonable structural declarations, not blanket any.
  • src/check.d.ts and src/testing.d.ts type the ./check and ./testing subpaths. index.d.ts re-exports the testing helpers via export * (they ship from both entry points) to avoid duplication.
  • package.json: types-first export conditions for ., ./check, ./testing (nodenext requires types before default), the top-level types, and index.d.ts added to files.

Tests

  • Type-fixture (test/types/): imports the documented surface and USES it at real signatures under strict + nodenext (matching the scaffold's tsconfig), so a wrong signature fails compile.
  • TS7016 counterfactual: moves index.d.ts aside and asserts the bare import errors TS7016 with non-zero tsc, then restores it, proving the overlay is load-bearing. Before: tsc exit 2 (TS7016). After: exit 0.
  • Drift guard: asserts the overlay's named exports exactly match index.js's runtime exports, so a future export added without a type is caught.
  • Full suite: pass, 0 fail. The 4-app dogfood (blog e2e + website/docs/ui-website prod boot) confirms the exports edit did not break runtime resolution (all three subpaths still import() at runtime). The scaffold suite passes.

Review

3 type tests green. A self-review found 4 type-accuracy nits (the Session.data shape was confidently wrong, redisStore/SessionStorage.save imprecise, a drift-test filename typo), all fixed and re-verified clean.

Docs

packages/server/AGENTS.md (new type-overlay note), agent-docs/typescript.md (both runtime packages now ship a type overlay). I deliberately did NOT wire webjs typecheck into scaffold CI in this PR (a separate follow-up). This PR closes the declaration gap that blocked it.

t added 3 commits June 3, 2026 21:05
@webjsdev/core shipped an index.d.ts + a types export condition, but
@webjsdev/server shipped neither, so under strict + nodenext a TS app's
import { createRequestHandler, cors, cache, ... } from '@webjsdev/server'
emitted TS7016 (no declaration file). That blocked the webjs typecheck-in-CI
story and left a core import untyped for every TS app. Ship a hand-authored
index.d.ts overlay typing every named export (precise for the high-traffic
public API, reusing core's PageProps/LayoutProps/RouteHandlerContext), plus
src/check.d.ts and src/testing.d.ts for the subpaths, and add types-first
export conditions. A drift guard asserts the overlay matches index.js's
runtime exports; a fixture + a TS7016 counterfactual prove the fix.

Closes #310
…sses

The Conventions CI step rejects any .ts under packages/{core,server,cli,
ts-plugin} that is not a .d.ts. The new type fixture was server-exports.test-d.ts
under packages/server/test/, whose name ends in .test-d.ts (not .d.ts), so the
buildless grep flagged it as TS source in a buildless package. Every other
.test-d.ts already lives at the repo-root test/types/ (outside packages/), so
move the fixture + its nodenext runner there to match the convention; the drift
guard stays near the package (a .mjs, which the grep ignores).
@vivek7405
vivek7405 merged commit 50428c4 into main Jun 3, 2026
5 checks passed
@vivek7405
vivek7405 deleted the feat/server-type-declarations branch June 3, 2026 15:52
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

Ship type declarations for @webjsdev/server (fix TS7016 on import)

1 participant