typecheck is the type safety the rest of KosmoJS leans on, run on demand.

pnpm typecheck          # every folder, plus the project root
pnpm typecheck admin    # just this folder
pnpm typecheck .        # project root only
pnpm typecheck . admin  # project root and admin

Typecheck is a manual run. The dev server and the build do not typecheck before transpiling.

So a stale defineRoute<"users/[id]">, left behind after renaming api/users/, is a compile error neither of them will mention - the bundle is emitted and the route 404s.

This is the command that catches it, in CI or before you commit.

If you need it running automatically before pnpm build

Add a prebuild script in package.json:

package.json

{
  "scripts": {
    "prebuild": "pnpm typecheck"
  }
}

By default the project root checks nothing of yours - include code you want typechecked.

Under the hood

It runs tsc --project <tsconfig> --noEmit in sequence, using the typescript version installed in the project: one run per selected source folder, plus one for the project root.

Every selected tsconfig is checked, even after one of them fails. A failing folder does not hide the state of the others, so one run tells you everything there is to fix rather than the first thing.

The command exits 1 if any run reported errors, and 0 only when all of them passed - so pnpm typecheck works as a CI gate without any extra wiring.

Why separate runs

Each source folder has its own tsconfig.json with its own path mappings. That covers everything in the folder, sidecar entries included. A single tsc over the whole project would resolve them against the wrong one, so the folders are checked one at a time instead.

Opting a folder out

A folder whose config carries typecheck: false is left out of every run. Useful for a sidecar wrapping third-party JavaScript, or a folder mid-migration where a red tsc is noise rather than signal.

src/mailer/kosmo.config.ts

defineConfig({
  // ...
  typecheck: false,
})

Naming it explicitly does not force the issue - pnpm typecheck mailer reports that the folder opts out and checks nothing.

The folder still builds and still runs; only typechecking skips it.

Selective typechecking

Provide no arguments and every source folder is checked, along with the project root.

# every folder, plus the root
pnpm typecheck

Provide one or more names and only those are checked, project root ignored.

# one folder, no root
pnpm typecheck admin

The command fails loudly if a name is not a folder in src/ with a valid kosmo.config.ts.

Provide . and only project root is checked, no source folders.

# the root, no folders
pnpm typecheck .

Provide . with folder name(s) and you get the root checked along with the provided names.

# the root and admin folder
pnpm typecheck . admin

By default the project root checks nothing of yours - include code you want typechecked.