.gio/

The working directory GioJS writes in the project root: client bundles, stylesheets, caches, fonts and the generated route types.

.gio/
  build/
    manifest.json        what the last build produced
    entries/             generated hydration entry files
    css-entries/         generated stylesheet entry files
    static/chunks/       client bundles        -> /_next/static/chunks/
    static/css/          route stylesheets     -> /_next/static/css/
  cache/
    pages/               the page cache's disk tier
    images/              optimized images
  fonts/                 [[fonts]] files and fonts.css -> /_gio/fonts/
  routes.d.ts            route types
  css-modules.d.ts       types for CSS imports
  ipc-<id>.sock          worker sockets (Unix)

Reference

The directory is created in the project root (the parent of app/). The socket files are the exception: they go in the .gio/ of the directory the server was started in, normally the same one.

routes.d.ts

Declares every page and route.ts pattern with its params in the global GioJS.RegisteredRoutes interface. href(), useParams(), PageProps, GetServerSideProps, RouteHandler and the other route-typed helpers read it, so a pattern that is not one of your routes fails tsc:

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

css-modules.d.ts

Types import styles from './x.module.css' as a map of class names to strings, and lets plain .css imports through. routes.d.ts references it, so including one includes both.

Examples

tsconfig.json and .gitignore

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

.gio/

Projects made with create-giojs have both already.

Types in CI

On a fresh checkout the type files do not exist until the server has started once. Write them without a server before tsc:

npx gio typegen
npx tsc --noEmit

pnpm exec gio typegen
pnpm exec tsc --noEmit

yarn gio typegen
yarn tsc --noEmit

bunx gio typegen
bunx tsc --noEmit

Good to know

• Everything in .gio/ is regenerated, so never commit or edit it. Deleting it while the server is stopped is safe; you lose the page and image caches.
• The dev watcher ignores .gio/, so the files GioJS writes never restart the worker.
• The page cache directory may not be, contain or sit inside app/ or public/: startup refuses such a [cache] disk_path.
• Two servers started from the same project share .gio/: the build, the caches and the type files. Give each its own GIO_CACHE_DIR if they must not share cached pages.
• A standalone build folder has its own layout (static/, worker.js, a .gio/manifest.json); see Standalone.

Related

• TypeScript - typed routes.
• gio typegen, gio routes
• Caching Layers, Environment variables

Version history