Files and folders — tcm-ts

36. Files and folders

What tcm init creates, what tcm writes as it works, and what to keep in version control.

myproject/
  package.json            "#codebase" and "#tcm/host" imports; your npm dependencies
  tsconfig.json           compiler options (see compiler options)
  .mcp.json               tcm mcp, the tools AI agents use to work in the codebase (see agents)
  AGENTS.md               a note for agents on working in a codebase (added to, if you have one)
  scratch.ts              where you write; any top-level .ts or .tsx file is a scratch file
  .tcm/
    codebase.sqlite       the codebase: definitions, names, history, branches, patches, todo
    codebase/             the #codebase modules your scratch files import (generated)
    cache/                every definition as a runnable module, by hash, what npm packages' code does
                          (npm-facts/), and server code's copies of the packages it uses (server_modules/:
                          hard links, for React's server environment) (generated)
    src/                  every named definition as a read-only file, for debuggers (generated)
    data/                 app data: tables, sessions, jobs (created when an app first runs)
    apps/                 production builds, by hash (tcm build / tcm start)
    web/, build/          working files for tcm dev and tcm build (generated)
    examples/             doc examples, as runnable modules (generated)
    pack/                 packages made by tcm pack, by package name (generated)
    compiled/             component modules as React Compiler makes them, by their text (generated)
    secret, tls/          the server's session secret and TLS certificate, once there are any
    .gitignore            ignores everything above except codebase.sqlite

36.1 What to keep

  • .tcm/codebase.sqlite is the codebase. Everything else in .tcm/ except data/ is generated from it and rebuilt when missing. To share a codebase, use sync (tcm push / tcm pull); copying the file works too. Its long texts (a definition's code and source, metadata, history's namespace nodes: 1 KB or more) are kept zstd-compressed; tcm compact compresses those an older tcm kept as written, and gives back the space nothing uses. .tcm/cache keeps a module for every version of the code it's run or checked, which tcm compact prunes to what some branch uses.
  • .tcm/data/ is your app's data. Back it up like any database; don't commit it (it holds sessions), and don't commit secret or tls/ either.
  • package.json, tsconfig.json are worth committing: they're your project's packages and compiler settings, and so are .mcp.json and AGENTS.md, so the agents anyone uses here know how to work in it (agents).
  • Scratch files are optional to keep: once code is added, it lives in the codebase.

tcm init writes .tcm/.gitignore, which leaves only codebase.sqlite to commit: generated directories, app data and secrets are all ignored.

36.2 The two imports

tcm init adds these to package.json's imports:

  • #codebase, #codebase/<namespace>: your saved definitions, as modules. They're regenerated whenever names change, so your editor's autocomplete and type checking always match the codebase.
  • #tcm/host: tcm's server host, what the server library runs on (the call, the app's SQLite files, transactions, jobs): for a library of server code, not for apps, which import the server library.

36.3 Generated modules

.tcm/cache/<hash>.ts holds each definition as a module, with current names spliced in and imports by hash (<hash>.tsx when it uses JSX). Node runs these directly; there's no build step. Modules Node's type stripping can't run (JSX, and enums or namespaces from imported projects) are compiled as they load. You can read them, but there's no need to: tcm view, and in VS Code Go to Definition, show the source.

built from c482a14e