TypeScript

Set up TypeScript in a GioJS app, type routes from your own folders with .gio/routes.d.ts, and find every type @gio.js/core and @gio.js/react export.

import type { PageProps } from '@gio.js/core';

export default function Post({ params }: PageProps<'/posts/:id'>) {
  return <h1>Post {params.id}</h1>; // params: { id: string }
}

GioJS runs TypeScript as is: the worker loads .ts and .tsx through tsx and bundles client code with esbuild, so there is no compile step and type errors never stop the server. Checking types is the job of tsc --noEmit, in your editor and in CI.

tsconfig.json

The TypeScript starter ships this file:

{
  "compilerOptions": {
    "target": "ES2022",
    "lib": ["ES2022", "DOM"],
    "module": "ESNext",
    "moduleResolution": "Bundler",
    "noEmit": true,
    "jsx": "react-jsx",
    "strict": true,
    "noUncheckedIndexedAccess": true,
    "noImplicitReturns": true,
    "paths": {
      "@/*": ["./*"]
    }
  },
  "include": ["app", "components", ".gio/routes.d.ts"]
}

• ".gio/routes.d.ts" in include turns on typed routes and the types of CSS imports. gio doctor warns when it is missing.
• moduleResolution: "Bundler" matches how esbuild resolves imports, and lets TypeScript read the packages' exports maps (@gio.js/core/testing, @gio.js/core/server-only).
• paths and jsx settings are honored on the server and when bundling: the worker, the client bundles and standalone bundles all use the project's tsconfig.json (or jsconfig.json), even when the server starts from another directory.

Add a script so CI checks types. Run gio typegen first so the route types exist on a fresh checkout:

{
  "scripts": {
    "typecheck": "gio typegen && tsc --noEmit"
  }
}

The JavaScript starter (create-giojs --js) uses a jsconfig.json with checkJs: false and types its exports through JSDoc: /** @type {import('@gio.js/core').GetServerSideProps<{ post: Post }, '/posts/:id'>} */.

Typed routes

GioJS writes .gio/routes.d.ts from your app/ folder: one entry per page and route.ts, keyed by its route pattern, in the global GioJS.RegisteredRoutes interface. href(), useParams() and every route-typed type of @gio.js/core read it, so a pattern that is not one of your routes fails tsc, editors autocomplete patterns, and params need no annotations.

/// <reference path="./css-modules.d.ts" />
declare global {
  namespace GioJS {
    interface RegisteredRoutes {
      '/': Record<string, never>;
      '/api/posts/:id': { id: string };
      '/blog/:slug': { slug: string };
      '/docs/*slug': { slug: string };
      '/shop/*path?': { path?: string };
    }
  }
}
export {};

The file is rewritten at every server start (gio dev restarts on file changes, so it stays current) and by gio typegen, which needs no server and no secrets: a route.ts that fails to import is still typed. It is generated output; keep .gio/ out of git.

Route patterns

href

href(pattern, params) from @gio.js/react builds a URL from a registered pattern, encoding each param (a catch-all keeps its slashes). Static routes take no second argument, and an optional catch-all may leave it out:

import { href } from '@gio.js/react';

href('/blog/:slug', { slug: 'hello world' }); // '/blog/hello%20world'
href('/docs/*slug', { slug: 'a/b c' });       // '/docs/a/b%20c'
href('/shop/*path?');                         // '/shop'
href('/blgo/:slug', { slug: 'x' });           // tsc: not assignable to '/' | '/blog/:slug' | ...

ParamsOf, RouteParamsOf, ParamsFromPattern, StaticParamsOf

Every route-typed generic of @gio.js/core (PageProps, GetServerSideProps, GsspContext, RouteHandler, GioRequest, ActionArgs, GenerateMetadata, GetStaticPaths) takes a RouteOrParams: a pattern ('/blog/:slug') or a params shape ({ slug: string }). These helpers do the resolving and are exported for your own generics:

Before .gio/routes.d.ts exists, these accept any pattern and parse its params from the string, so the @gio.js/core types work on a fresh checkout. href() and useParams<pattern>() from @gio.js/react do the same: href('/blog/:slug', { slug }) typechecks before the first server start, and still requires slug.

GioRegisteredRoutes

@gio.js/react's GioRegisteredRoutes extends GioJS.RegisteredRoutes. Routes you added to it by hand still type href(), but not the @gio.js/core types; declare extra routes on the global registry instead:

declare global {
  namespace GioJS {
    interface RegisteredRoutes {
      '/legacy/:id': { id: string };
    }
  }
}
export {};

CSS Module types

.gio/routes.d.ts references .gio/css-modules.d.ts, which types import styles from './card.module.css' as { readonly [className: string]: string } and a plain import './globals.css' as a side-effect import. No setup beyond the include entry.

Reference

Every type in these tables is a type-only export: import it with import type. The packages ship declaration files, so tsc --noEmit checks against them without compiling the framework. @gio.js/core also exports three classes, values you can use as types too: GioEventStream, and the MalformedBodyError and UnsupportedMediaTypeError that req.formData() and req.json() throw.

Pages and layouts

Data fetching

Actions and forms

Route handlers and realtime

Metadata

Middleware, config and plugins

Sessions, cookies and revalidation

Client router and components

Testing

Examples

A typed page with getServerSideProps

import { notFound } from '@gio.js/core';
import type { GetServerSideProps, InferPageProps, GenerateMetadata } from '@gio.js/core';

interface Post {
  slug: string;
  title: string;
  body: string;
}

const posts: Post[] = [{ slug: 'hello', title: 'Hello', body: 'First post.' }];

export const revalidate = 300;

export const getServerSideProps = (async (ctx) => {
  const post = posts.find((p) => p.slug === ctx.params.slug); // ctx.params: { slug: string }
  if (post === undefined) notFound();
  return { props: { post }, tags: [`post:${post.slug}`] };
}) satisfies GetServerSideProps<{ post: Post }, '/blog/:slug'>;

export const generateMetadata: GenerateMetadata<'/blog/:slug'> = (ctx, { props }) => {
  const post = props?.['post'] as Post | undefined;
  return { title: post?.title ?? ctx.params.slug };
};

export default function BlogPost({ post }: InferPageProps<typeof getServerSideProps>) {
  return (
    <article>
      <h1>{post.title}</h1>
      <p>{post.body}</p>
    </article>
  );
}

satisfies keeps the exact return type, so InferPageProps reads { post: Post } off it. notFound() returns never, which narrows post.

A typed route handler

import { notFound } from '@gio.js/core';
import type { RouteHandler } from '@gio.js/core';

const titles: Record<string, string> = { '1': 'Hello' };

export const GET: RouteHandler<'/api/posts/:id'> = (req) => {
  const title = titles[req.params.id];
  if (title === undefined) notFound(); // a JSON 404
  return { id: req.params.id, title };  // 200 application/json
};

A typed action

import { redirect } from '@gio.js/core';
import type { ActionArgs, WithActionData } from '@gio.js/core';
import { GioForm } from '@gio.js/react';

export async function action(req: ActionArgs) {
  const form = await req.formData();
  const email = String(form.get('email') ?? '');
  if (!email.includes('@')) {
    return { status: 422, data: { error: 'Enter a valid email address.' } };
  }
  return redirect('/subscribe/thanks');
}

export default function Subscribe({ actionData }: WithActionData<typeof action>) {
  return (
    <GioForm>
      <input name="email" type="email" />
      {actionData?.error && <p role="alert">{actionData.error}</p>}
      <button type="submit">Subscribe</button>
    </GioForm>
  );
}

actionData is { error: string } | undefined: the redirect is left out, because it never re-renders the page.

Typed links and params

import { GioLink, href, useParams } from '@gio.js/react';

export function PostNav() {
  const { slug } = useParams<'/blog/:slug'>();
  return (
    <nav>
      <GioLink href={href('/blog/:slug', { slug: 'hello' })}>First post</GioLink>
      <span>Reading {slug}</span>
    </nav>
  );
}

A typed sitemap

import type { MetadataRoute } from '@gio.js/core';

export default function sitemap(): MetadataRoute.Sitemap {
  return [
    { url: '/', changeFrequency: 'daily', priority: 1 },
    { url: '/blog/hello', lastModified: new Date('2026-10-01') },
  ];
}

Relative URLs resolve against GIO_SITE_URL.

Good to know

• Type errors never stop gio dev or gio start: run tsc --noEmit to see them.
• A catch-all param is one string with / separators ('guides/setup'), in the types and at runtime; only getStaticPaths also accepts an array of segments.
• process.env values are typed as string | undefined by @types/node; GioJS adds no declarations for your variables.
• In generic code, ActionArgs<P>['params'] is a ParamsOf<P>, not a P: TypeScript leaves the conditional type unresolved while P is a type parameter.
• gio.config.ts and middleware.ts are TypeScript too: wrap them in defineConfig() and defineMiddleware() for completion. Unknown gio.config.ts keys are an error at startup.

Related

• Typed routes in Linking & Navigating
• href, useParams and gio typegen
• Dynamic routes and the .gio directory
• getServerSideProps, action and generateMetadata
• Environment Variables, Endpoints and Headers

Version history