All docs

Docs · Reference

Static files

serve a site from a stack

The web head can serve files straight from your stack — CSS, images, a whole prerendered site — with no backend, via the built-in txco://static op.

Drop a FILES/ directory in your workspace and txco apply. Any request whose path maps to a file in it is answered directly by the chassis — with the right content type, a content-hash ETag, and 304 Not Modified on a conditional GET. No rule to write, no service to run.

Drop files in FILES/

Put assets under FILES/, either workspace-wide or inside a stack:

my-app/
  FILES/                 # workspace-wide assets
    index.html
    styles.css
    img/logo.svg
  OPS/
    web/
      FILES/             # per-stack assets (take precedence when routed here)
        robots.txt
      100/...

txco apply uploads the tree (content-addressed — unchanged files dedup, so the cost is metadata, not bytes). Lookups are layered, first match wins:

  1. the routed stack’s own OPS/<stack>/FILES/<path>
  2. the workspace-wide FILES/<path>
  3. an embedded default (favicon.ico) as a last resort

It works out of the box

The bundled _sys/boot stack already runs txco://static at scope 50 — before routing — so files serve with nothing to configure, even on a host that isn’t routed to a stack yet:

WHEN @src == "http"
EXEC "txco://static"

The op self-gates: a request that doesn’t map to a file returns nothing and the flow continues to your own rules (or the 404 at the end). A hit emits the file bytes and halts, so a rule can never shadow a file (or add headers to its response).

Only GET and HEAD are static’s: any other method goes straight to your rules, so a POST /login reaches your app even when login.html exists.

The index is rebuilt on txco apply (a dbcache reload), never on the request path:

  • Workspace files (FILES/, OPS/<stack>/FILES/ on the chassis’s own disk) are held in memory, bytes and all.
  • Files a tenant ships with txco apply keep only their path → content-hash map in memory. Their bytes come from the content-addressed file store through a 64 MiB cache — local disk, or object storage on a fleet.

Clean URLs and indexes

txco://static resolves paths the way a static host does (try_files):

RequestServes
/index.html
/aboutabout.html
/blogblog/index.html
/app.jsapp.js (exact — a path that already has an extension never falls back)

Only / falls back to the root index.html; any other unmatched path is a miss. A path with a segment starting with . (/.env, /.well-known/…) is never a static file, so your rules can answer it.

A miss under a directory that exists in FILES/ is a hard 404 (and halts) when the path looks like a file — nested, with an extension in its last segment. So /assets/gone.js is a 404 once any assets/* file exists, instead of reaching your app; /assets/page (no extension) still falls through, for an app route that shares the prefix.

Content type is resolved from the extension (a pinned table for the common web types, then the OS database, then content-sniffing for in-memory files without one).

Caching

Every file carries a strong ETag (its content hash). A conditional GET whose If-None-Match names it — in a list, as a weak W/ tag, or * — gets 304 Not Modified without the bytes being fetched.

FileCache-Control
HTML, markdownmax-age=0, must-revalidate — the entry point always revalidates, so a deploy’s new asset URLs are picked up
under a prefix marked immutablepublic, max-age=31536000, immutable
anything elsepublic, max-age=3600

A prefix is marked immutable by a marker file, FILES/_txco/immutable/<prefix>/_txco_mark (its contents are ignored). Mark only directories whose file names carry a content hash, such as a bundler’s app/immutable/: those names change whenever the bytes do. A Web ABI build’s installer writes the markers for you.

Static does not compress (the hosted edge does) and does not answer Range requests.

Limits

  • Workspace layers: 1 MiB per file, 2048 files, 64 MiB total — anything over the cap is skipped at load time (and logged), so a runaway FILES/ tree can’t exhaust memory.
  • Tenant files (shipped with txco apply) have no serving limit. One over --filecas-max-file-bytes (10 MiB) is served without being cached. A single very large asset still belongs on a CDN.

:::warning A request path with any segment that starts with _ is never served over HTTP — it’s treated as private (e.g. FILES/_mail/ email templates: readable by ops, never public). So a file at FILES/_app/app.js returns nothing, not a leak.

The one exception is a path its stack marks public, with a marker file at FILES/_txco/public/<root>/_txco_mark, where <root> is the path up to and including its first _ segment (_app, assets/_chunk.js). A Web ABI build’s installer writes these for the files in its public/ tree — which is how SvelteKit’s _app/ is served — and anything else under _ stays private. :::

Markdown for agents

A site can answer an agent that asks for markdown with markdown, and a browser with its HTML, at the same URL:

GET /about
Accept: text/markdown

HTTP/1.1 200 OK
Content-Type: text/markdown; charset=utf-8
Vary: Accept

Add a _markdown inlet beside the stack the hostname is bound to, with the pages as .md files and at least one op:

OPS/
  web/
    100/...
    _markdown/
      FILES/index.md         /
      FILES/about.md         /about   (or FILES/about/index.md)
      9000/not_found.txcl    any other page, in markdown

Its existence is the opt-in, as for <stack>/_mail and <stack>/_tcp: there is nothing to bind or configure, and an inlet gets no hostname of its own.

Who enters it. A GET or HEAD of a page (the root, or a path whose last segment has no extension) whose Accept names text/markdown with a q at least that of text/html. text/html’s q comes from its most specific match: text/html, then text/*, then */*. So:

AcceptGets
text/markdownmarkdown
text/markdown, text/html;q=0.9markdown
text/markdown, text/htmlmarkdown (naming markdown at all is the signal; no browser does)
a browser’s, */*, or noneHTML
text/html, text/markdown;q=0.5HTML

Everything else stays on the stack: other methods, and asset paths (/app.js, /robots.txt), so an agent still gets those as they are.

What answers. Static serves the inlet’s FILES/ first, by the same rules with .md in place of .html (/ → index.md, /about → about.md or about/index.md), as text/markdown; charset=utf-8 with an ETag. The inlet’s files only: never the stack’s, the chassis-wide layer or the embedded defaults. A page with no file runs the inlet’s ops, which answer the rest (a page built from data, or a markdown 404) and set the content type themselves.

The headers. Every page answer on the host, from either stack, static or op, gets Vary: Accept, added to any Vary the stack set. An HTML page whose markdown is a file in the inlet also gets

Link: </about.md>; rel="alternate"; type="text/markdown"

and that URL serves the file to anyone, whatever their Accept, when the stack has no about.md of its own. A page an op renders as markdown isn’t advertised: the chassis can’t know it exists without running it. A host without a _markdown inlet gets neither header.

Note

A stack with no ops counts as withdrawn (txco deactivate leaves an empty version), so an inlet of files alone is never entered: keep at least one op, such as the markdown 404. A streamed answer doesn’t get the two headers.

Dynamic pages without a backend

Need a page built from computed data rather than a file on disk? txco://web-render reads a value from the envelope, optionally renders it, and writes the HTTP response — see the builtins reference:

# scope 200 returns what scope 100 produced, rendered as HTML
WITH source = ".text", wrap = "markdown-to-html"
EXEC "txco://web-render"

WITH options: source (envelope path, default .text), wrap (raw | html | markdown-to-html), content_type, status. It always halts. (You can also shape @web.res.* directly in a rule — see the web inlet.)

A SvelteKit (or any framework’s) site

A framework’s build reaches a stack through the Web ABI: the build’s public/ becomes the stack’s FILES/, and its ops (an SPA fallback, a 404 page, a catch-all) run after yours. For SvelteKit, @txco/svelte-adapter-thankscomputer 0.3 writes the build:

// svelte.config.js
import adapter from '@txco/svelte-adapter-thankscomputer';

export default {
  kit: { adapter: adapter({ out: 'txco-web', fallback: '200.html' }) },
};
# txco.yaml at the workspace root
stacks:
  web:
    abi: www/txco-web
vite build                      # writes www/txco-web/
txco web check www/txco-web     # probes it on a scratch chassis
txco apply                      # ships the stack to your tenant

Prerendered routes serve their own HTML through the try_files resolution above. A navigation to a client-rendered route gets the app shell from the build’s spa-fallback op, so deep links and hard reloads still render; one that matches no route gets the shell with a 404 (spa-404); anything else gets a plain 404 (not-found).

For Nuxt (and other Nitro frameworks), @txco/nitro-preset writes the same kind of build:

// nuxt.config.ts
export default defineNuxtConfig({ nitro: { preset: '@txco/nitro-preset' } });
nuxt generate                   # writes txco-web/
txco web check txco-web
txco apply

nuxt generate prerenders every page it can crawl. A navigation to a page that doesn’t exist gets Nuxt’s 404.html with a 404, and an ssr: false app gets its shell with a 200 instead.

A plain Vite app (React, Vue, Solid, Preact or vanilla) adds @txco/vite-plugin. It copies dist/ into the build after vite build:

// vite.config.ts
import txco from '@txco/vite-plugin';

export default defineConfig({ plugins: [react(), txco()] });

Every page path gets index.html with a 200, so the client router renders it. A multi-page build gets its 404.html with a 404 instead.

React Router (framework mode) adds @txco/react-router as a preset, and Astro adds @txco/astro as an integration:

// react-router.config.ts
export default { ssr: false, presets: [txco()] } satisfies Config;
// astro.config.mjs
export default defineConfig({ integrations: [txco()] });

React Router’s route table decides the status: a known route gets the shell with a 200, any other path the shell with a 404. An Astro site gets its 404.html with a 404. SolidStart builds through the Nitro preset.

Edit this page · View as markdown