tcm blog

The Client/Server Boundary

Andrew Lisowski — Sun, 08 Nov 2026 00:00:00 GMT

Every full-stack app has a line running through it: some code runs on the server, some runs in the browser, and a network sits between them. Most tools make you draw that line yourself.

You might split your code into a server/ and a client/ package. You might write "use server" and "use client" at the top of files. You might write an API route, then a fetch to call it, then types to keep the two in step.

All of that is bookkeeping, and it goes wrong in familiar ways. A secret ends up in the browser bundle. A file that imports node:fs gets pulled into the client, and the build blows up. A deploy goes out, and a tab that was already open calls an endpoint that changed shape under it.

In tcm, you don't draw the line. tcm works it out from your code.

Writing it

Here's a whole app:

import { readFileSync } from "node:fs";

export async function hostCount(): Promise<number> {
  return readFileSync("/etc/hosts", "utf8").split("\n").length;
}

export const render = (n: number) => `hosts: ${n}`;

export async function main() {
  document.querySelector("#app")!.textContent = render(await hostCount());
}

There's no annotation anywhere. hostCount reads a file, so it runs on the server. main touches document, so it runs in the browser. render uses neither, so it runs wherever it's called. When main calls hostCount, that call goes over the network.

The rules you write by are short:

Use Node, and your code runs on the server. That's node:* modules, process, Buffer, an npm package that needs Node, or tcm's server library (tables, sessions, cookies).
Use the DOM, and it runs in the browser.
Use neither, and it runs anywhere. It ships to whichever side calls it, or both.
Send plain data. JSON, plus Date, Map, Set and BigInt. A function or class instance is refused with a message saying what couldn't be sent, rather than quietly turning into {}.

And if you're ever unsure, tcm view tells you where a definition runs and why: "runs on the server: it uses node:fs".

Why this is hard with files

A file is a bag of things. Import one function from it, and you pull in everything the file imports, too. So bundlers have to decide where code runs one file at a time. If a file mixes a server helper with something the browser needs, the tools can't split it. That's why you end up annotating files and sorting them into folders: you're doing the analysis for them.

In tcm, there are no files to split. Your code lives in a database (a codebase), and each definition is its own row: one function, one constant, one type. Each row records exactly what that definition uses: other definitions (by hash), globals like document or process, and the npm exports it imports.

So "where can this run?" is a question about one small node in a graph, and its edges are already written down.

How it works under the hood

1. What each definition uses directly

tcm looks at each definition on its own first.

A definition needs the server if it uses a node: module, a Node global (process, Buffer), tcm's server library, or an npm export whose browser build still imports Node's modules. tcm reads that last one from the package's code, so it doesn't rely on a list of known packages.

A definition needs the browser if it uses a DOM global (document, window, IntersectionObserver), a client-side React API like useState, or handles an event.

Only code that runs counts. Types are erased, so (el: HTMLElement) => … doesn't put anything in the browser. el instanceof HTMLElement does.

2. Following the graph

Then the answer spreads along the edges. If loadConfig uses node:fs, and greeting uses loadConfig, then greeting needs the server too. tcm keeps the chain, so it can tell you why: "uses app.loadConfig, which uses node:fs".

It repeats until nothing changes, so code that calls itself (or two functions that call each other) gets the right answer too.

3. Planning the app

To build an app, tcm walks the graph from its entry point (main, or a React component).

Code that can run in the browser goes in the browser bundle, and tcm keeps walking through what it uses.
When it reaches an async server function, it stops. That function becomes an endpoint, and nothing behind it is followed into the browser.

4. Stubs in place of server code

In the browser build, each endpoint's module is swapped out before the bundler ever resolves it. In its place is a one-line stub:

export const hostCount = remote("<hash of hostCount>", "app.hostCount");

remote sends the arguments to POST /__tcm/rpc/<hash>, and turns the reply (or the error) back into a promise. The server function's code, and everything it uses, never reaches the browser.

5. The server side

On the server, the only callable functions are the endpoints the plan found. Anything else is refused.

TypeScript's types are gone at runtime, so an endpoint is effectively public input. tcm derives a runtime schema from each server function's parameter types, and checks every call against it. Wrong types, missing fields or extra arguments get a 400 before your function runs. Calls also have to come from the same origin and send JSON, which rules out cross-site form posts.

6. Calls by hash

The browser calls a server function by its hash, not its name or a route. A hash never changes meaning: if hostCount changes, it gets a new hash.

So deploys don't break open tabs. A tab loaded before a deploy keeps calling the hashes it was built with, and the server keeps those builds' endpoints callable.

The line falls out of the graph

None of this is a separate feature bolted on. Once code is stored as a graph of small definitions, each with its uses written down, the boundary is just a question you can ask the graph.

You write functions. tcm works out which side of the network each one belongs on, and builds the bridge between them.

Code Validation

Andrew Lisowski — Sun, 08 Nov 2026 00:00:00 GMT

One thing that representing your code as a graph of values unlocks is far more incremental builds. Packages, files, folders and apps are a poor way to tell whether a piece of code needs to be checked again.

Traditional JS

An app might be split into packages like these:

core/: shared functionality for the apps
components/: frontend UI
apps/dashboard/: an internal dashboard
apps/client/: the user-facing UI

Whenever anything in core/ changes, everything that depends on core/ has to be rebuilt, re-linted and re-tested. Here that means validating every bit of code, even code that didn't change and doesn't use anything that did.

Values in tcm

In tcm, your code isn't organized into packages, files or apps. Each value is stored individually, and the imports between them form a graph. From that graph, we know exactly which code needs to be validated again.

Represented as a graph, the example above might look like this:

SomeType
someArr
ArrayRenderer
UserRenderer
DashboardApp
ClientApp

If we change someArr, we know exactly what needs to be validated again, and everything else can be skipped.

Build Superpowers

In traditional projects, it's very easy to introduce dead code (code that isn't used anywhere). Dead code makes your project bigger and slower. With tcm, it never gets there in the first place.

The graph does away with a lot of the complexity of the past:

Dead code elimination: code that isn't connected to the graph just isn't included.
Tree shaking: there's no need to shake out what isn't referenced.

Why Files

Andrew Lisowski — Sun, 08 Nov 2026 00:00:00 GMT

The core idea behind tcm is that there are no files: your code is stored in a database (called a codebase). But that raises the question: why do we store code in files at all?

Well, the answer is kind of obvious: that's just how computers work! But that's not the full story. Files are there because we put them there. Files help us define something, organize similar things into groups, and then group those further into folders. Seems necessary? Maybe not.

The downsides of files for code

So files and folders are (seemingly) good for organizing our code, but what baggage comes with them?

Placement comes with constraints - Putting a bit of code in a package seems simple, right? Not really. That package might only work on the server, so code the client needs can't go there. If you want that code on both the server and the client, you have to set up a third package to hold the shared code. You'll also have to make sure that package stays isomorphic, or else your bundle might blow up or your server might crash.
Files need managing - Is a value really used? We can try to rely on our tools, but cruft accumulates. Is the file too long? Too short? Too spread out? You need to decide ahead of time how much or how little should go where. That might make sense in the moment, but not as a project evolves.
Folders - And once you have files, which folder do you put them in? Oh, that changed? Now countless files have to change. Just like with files, we have to anticipate the ideal structure, then suffer later when it inevitably turns out to be slightly the wrong shape.

That's a whole lotta problems that aren't code! Files and folders are littered with hurdles that have nothing to do with shipping code, just with organizing it to appease the beast.

Knowledge bases

An interesting thing about knowledge bases is that the less organization, the better! Folders and organization are choices, and those choices mean constant maintenance and having to categorize things. If you free yourself from that, and instead keep a single flat folder of files that organizes itself through the connections between them, you start to do a lot less work.

Another concept found in knowledge bases is "evergreen notes". These notes are bite-sized concepts that you link together to form a web of thoughts and knowledge. With this, you don't repeat yourself much, but you have very detailed context embedded in the thoughts.

Could we apply these principles to code?

A graph of values

When you add code to your codebase, each value (types, constants, functions, classes) is stored as a row in a database. If you follow their imports, you get a big graph of how all the code in your program connects.

You can think of it just like a knowledge base. Instead of a directory of files with relative links to each other, it's a graph of bite-sized values.

Apps, packages and scripts become subsections of the graph, picked out into whatever output format we want. Need a package? It materializes with the things you need, and none of the things you don't. Because we work in values, we don't have to worry that an array lives in a server package: we just need the value.

Suddenly, all the problems of files are gone! (There are, of course, many new problems caused by this.) We didn't need to anticipate the needs of the future with how we structured our code's files. Instead, our code can transform to meet the demands of the moment.

Working on a feature? Pull all the relevant values into one file, or as many as you want. The code can meet your needs right there, no planning needed.

Files are human

Files are ultimately a tool for humans. Managing code the way tcm does, in a codebase, is a very different way of working. It's a bit easier to remember where a file is. After working in a codebase for a while, you get to know the lay of the land: you remember where that function is stored, like a mark on a map.

But that topology comes with constraints, and with our code as a graph, we can work around many of them.

Introducing tcm

Andrew Lisowski — Sat, 07 Nov 2026 00:00:00 GMT

tcm is a new way to store TypeScript. Instead of a folder of text files, your code lives in a codebase: a database of code. Each function, type and constant is stored on its own, under the hash of its code. Names are kept apart from the code, as labels that point at those hashes.

Writing code doesn't change. You write ordinary TypeScript in a scratch file, in the editor you already use. Once it typechecks, you add it to the codebase, which stores each definition in it. There's no new language: Node runs the stored code directly.

Keeping names apart from code makes everyday edits simpler. A rename moves a label, so no code is edited and nothing breaks. Changing a definition doesn't leave the code that uses it behind, either. tcm checks each place that uses it against the new version. The ones that still typecheck move to it, and the rest go on a todo list, with the reason.

Where it comes from

Most of the model is Unison's. Unison is a language built around storing code by its hash, and it showed what that makes possible: free renames, changes that carry through, scratch files that show values as you write, search by type, and history that knows a rename from an edit. tcm brings that model to TypeScript, and keeps the compiler, packages and editors people already use.

Sharing works as it does on Unison Share. Codebases are pushed and pulled by hash, and a contribution is a branch, reviewed as a diff of definitions rather than lines of text.

Your code as a graph

Each definition is stored with the hashes of what it uses, so a codebase is an exact graph of your code. A folder of files is a rough version of that graph: import one function from a file, and you depend on the whole file. With the exact graph, tcm knows what any change reaches, and much of what it does follows from that.

Tests run once. A test's result is kept with the hashes it reached. Only the tests a change reaches run again, and results travel with the code when you push and pull.
Apps ship only what they use. An app is bundled from what it reaches, so there's no dead code to remove.
Code runs where it belongs. Whether a definition runs on the server or in the browser is worked out from what it uses. Browser code calls a server function by importing it, with no routes or fetch calls. React server components work the same way, with no "use client" or "use server".
Deploys don't break open tabs. Calls from the browser to the server go by hash, and earlier builds stay served, so a tab keeps calling the code it loaded.

What goes away goes through each of these, and where it stops.

Try it

Install tcm and take the tutorial, or browse tcm's own code. tcm is developed in a codebase of its own, and its docs and this blog are pages in it.