#TypeScript Setup
Configure tsconfig for a Krate app and understand the generated types.
Krate compiles TSX itself (a Go lexer/parser), but you still get full editor
types via a standard tsconfig.json plus generated declarations.
#tsconfig.json
The scaffold ships a working config. The essentials:
{
"compilerOptions": {
"target": "ES2020",
"lib": ["ES2020", "DOM", "DOM.Iterable"],
"module": "ESNext",
"moduleResolution": "Bundler",
"jsx": "preserve",
"jsxImportSource": "@krate/runtime",
"strict": true,
"noEmit": true,
"skipLibCheck": true,
"esModuleInterop": true,
"baseUrl": ".",
"paths": { "@/*": ["./src/*"] }
},
"include": ["src", ".krate/types", "*.d.ts"]
}Notes:
jsx: "preserve"- Krate's compiler owns JSX transformation;tscis only used to typecheck (hencenoEmit).paths-@/*maps tosrc/*. The compiler reads the samepathsandbaseUrlfromtsconfig.jsonfor bundling resolution, so they stay in sync.tsconfig.jsonmay contain comments and trailing commas, andextends(a relative path or a package) is followed. Targets inpathsresolve relative tobaseUrlexactly astscdoes, so withbaseUrl: "."write"@/*": ["./src/*"]; an import that does not resolve fails the build at the import statement. A tsconfig that cannot be parsed is reported as a warning. WithbaseUrlset, a bare import that nopathsentry and no installed package satisfies is tried as a path under it (import Btn from "components/Btn"withbaseUrl: "src"); an installed package always wins. Asset imports through an alias (import logo from "@/assets/logo.png") work like relative ones.includemust cover.krate/typesso generated route/content types are visible.
#Generated types
krate types (or any build) writes:
| File | Provides |
|---|---|
.krate/types/routes.d.ts |
StaticRoute, DynamicRoute, Route, RouteParams |
.krate/types/content.d.ts |
Typed entries for configured collections |
.krate/types/**/*.krate.d.ts |
Go component declarations so import { X } from "./x.go" type-checks |
.krate/gen/content.ts |
Build-time content data (getCollection) |
Regenerate after adding pages or content:
krate typesFor Go components, run krate go:init once - it adds .krate/types to your
tsconfig include (see Go Components).
See Typed Routes & Content for usage.
#Global JSX types
@krate/runtime provides the global JSX namespace (intrinsics, ARIA, SVG
attributes, Krate.TypedRoutes). Ensure your tsconfig resolves it - either
via jsxImportSource above or a /// <reference types="@krate/runtime" />
in an ambient .d.ts.
src/krate-env.d.ts bridges Krate's globals like Head, Link, Image, and
Icon. It is generated (by krate dev, krate build or krate types) and
git-ignored by the scaffold, so run krate types once after cloning for editors
and tsc to see it. The scaffold's typecheck script does exactly that:
krate typecheck.
#Typechecking in CI
krate typecheckAdd this after krate build. It catches type errors the compiler tolerates
(Krate strips types rather than validating them). It generates the types, then
runs your project's tsc --noEmit without the errors tsc reports for
tier decorators. Any other
error fails it, including a misspelled decorator.
#Editor support
Tier decorators are errors to TypeScript, so editors underline them. The scaffold
turns that off with a language service plugin in tsconfig.json:
{
"compilerOptions": {
"plugins": [{ "name": "@krate/ts-plugin" }]
}
}For an existing project, install @krate/ts-plugin as a dev dependency and add
the entry above. In VS Code, run TypeScript: Select TypeScript Version and
choose the workspace version, since plugins load from your project.
Plugins only run in editors, which is why the command line uses krate typecheck
instead of tsc.
#How Krate compiles TypeScript
Before compiling a .ts/.tsx page, layout or component, Krate strips its
types with esbuild (built into the krate binary). Everything TypeScript
accepts is supported, including:
enum,const enumandnamespace(lowered to plain objects)- constructor parameter properties (
constructor(private a: number)) - decorators (standard, or legacy when
experimentalDecoratorsis set) - nested and conditional generics (
Map<string, Set<string>>), generic arrows (<T,>(x: T) => x),satisfiesandas const
Imports follow verbatimModuleSyntax: import type and inline type
specifiers are removed, every other import is kept. Use import type for
type-only imports from modules that have no runtime export of that name.
From your tsconfig.json, Krate honours experimentalDecorators and
useDefineForClassFields. TypeScript syntax errors fail the build with the
original file:line:col. Comment directives such as // @server still apply.
#Decorators
Decorators on classes and their members work on ordinary classes, in .js and
.jsx files too. Those always use standard decorators, since
experimentalDecorators is a TypeScript option.
A class component is compiled to a function component, so most decorators cannot apply to it: the build warns with KR3011. Decorators on class components are only supported for tiers.
#Strictness
Keep strict: true. Krate's generated types assume it. If you need looser
settings during a migration, scope them per-directory rather than globally.
Last updated: 2026-11-17
Contributors: Noinkin