Type checking

Fresh has no separate types package and no manual Props interface to fill in. The Vite plugin generates a small TypeScript scaffold next to your code on every dev run and every build. Routes import from that scaffold and get a fully-typed ctx, params, props.data, and middleware state. The types are inferred from the actual handler and page you wrote.

The .fresh/ directory#

When you start the dev server or run vite build, Fresh writes a .fresh/ directory at the project root. It contains two things.

• tsconfig.json. A base config that your project’s tsconfig.json extends. It sets jsx: "react-jsx", jsxImportSource: "preact", strict mode, and registers .fresh/types/** as a virtual root.
• types/. Generated .d.ts files mirroring the shape of your routes/ tree (route params, layout and middleware state, and so on).

The directory is regenerated whenever files in routes/ change. Add it to .gitignore. The scaffolder does this for you. The build always recreates it.

Info

If your editor flags ./$<name>.ts imports as missing in a brand-new project, run vite (or vite build) once. Until the plugin has executed, .fresh/types/ does not exist yet.

The $ files#

For every route, layout, middleware, app shell, and error page, Fresh exposes a sibling virtual module named $<filename>.ts. The files live in .fresh/types/, but TypeScript’s rootDirs makes them resolvable as if they sat next to the file.

Each export is a typed identity helper. It accepts the function you would write anyway and returns it unchanged, but with ctx, params, props.data, and middleware state already narrowed for that exact route.

routes/users/[id].tsx

import { handler, page } from "./$[id].ts";

export const handlers = handler((ctx) => {
  // ctx.params.id is `string`, generated from the [id] segment.
  return { data: { id: ctx.params.id } };
});

export default page((props) => {
  // props.data is inferred from the handler return.
  return <h1>User {props.data.id}</h1>;
});

State and ParentState#

_middleware.tsx files compose. The generated ./$_middleware.ts exports a ParentState type that represents whatever state the middlewares above this one have already added. Extend it to add your own fields.

routes/admin/_middleware.tsx

import { middleware, ParentState } from "./$_middleware.ts";

export interface State extends ParentState {
  user: { id: string; isAdmin: boolean };
}

export default middleware(async (ctx) => {
  const user = await loadUser(ctx);
  if (!user.isAdmin) return new Response("Forbidden", { status: 403 });
  return ctx.next({ ...ctx.state, user });
});

Routes nested under admin/ automatically see ctx.state.user typed through the same generated chain.

The project tsconfig#

The project tsconfig.json should extend .fresh/tsconfig.json. That is what wires up the JSX runtime, the strict-mode flags, and the $ lookups.

tsconfig.json

{
  "extends": "./.fresh/tsconfig.json",
  "compilerOptions": {
    "module": "esnext",
    "moduleResolution": "bundler",
    "allowImportingTsExtensions": true,
    "noEmit": true,
    "types": ["vite/client"]
  }
}

Continuous integration#

Run the dev server or vite build once before tsc --noEmit so that .fresh/types/ exists. If a CI step only typechecks, a one-shot vite build is enough. The scaffolder adds the right scripts to package.json, so most projects can just run them in order.

Troubleshooting#

Almost every issue with the generated types comes down to .fresh/ being missing or out of date. Running the dev server or vite build regenerates it from scratch.

A few specific cases come up often.

The editor shows red squiggles on ./$… imports in a fresh checkout. The plugin generates the types on first startup, so this clears once vite (or vite build) has run at least once.

ctx.params looks stale after renaming a segment. The generator picks up file changes while the dev server is running. If it is not running, restart it or rerun the build.

Cannot find module './$…' appears after a git clean. This is expected because .fresh/ is gitignored. The next vite invocation recreates it.