Build one by one.
Stitch to bundle.

download 01 / Install

Install Stitch

npm i @vkdatta/stitch -g

Stitch is a build tool for your website — and for any project made of text files. Install it globally, then run it inside the project you build and deploy.

stitch build     # compose src/ into dist/
stitch dev       # build, serve, and rebuild on every change
stitch reverse   # rebuild src/ from a built dist/
stitch help

folder_open 02 / Structure

Keep your source organized

project/
├── src/
│   ├── index.html
│   ├── repo.html
│   ├── components/
│   │   ├── header.html
│   │   └── footer.html
│   ├── data/
│   │   └── version.txt
│   ├── style.css
│   └── script.js
└── package.json

Stitch reads src/ and writes the deployable site to dist/. Static assets are copied into dist/stitch_assets/. Every text file — HTML, JavaScript, CSS, plain text, source code in any language — is processed for Stitch directives; binary files are copied as they are.

extension 03 / Components

Consume a component

<stitch src="components/header.html"></stitch>

<main>
  <h1>Hello</h1>
</main>

<stitch src="components/footer.html"></stitch>

Paths are resolved relative to the file containing the tag. This lets nested files reference components relative to their own location. The referenced file may itself contain additional <stitch src> calls — composition is recursive.

Extension handling

When the referenced path has no extension, Stitch tries .html first, then a file with exactly that name (such as Makefile). A path with an extension is used as written — and it may be any text file, not only HTML. See Any Language.

<stitch src="/tags/opening"></stitch>
resolves as: src/tags/opening.html

<stitch src="data/version.txt"></stitch>
resolves as: src/data/version.txt

data_object 04 / Data

Reuse one component with different values

A reusable component declares placeholders:

<stitch reusable></stitch>

<article class="card">
  <span>{{icon}}</span>
  <h2>{{title}}</h2>
</article>

A caller supplies values through data-* attributes:

<stitch src="components/card.html"
     data-title="API"
     data-icon="bolt"></stitch>

Stitch produces:

<article class="card">
  <span>bolt</span>
  <h2>API</h2>
</article>

Substitution happens at build time. The same component can be consumed repeatedly with different values. Substitution may occur in text or attributes, in any file type, and values can be passed by id too: $stitch-drop('card', data-title="API"). The <stitch reusable> declaration itself never appears in generated output.

build 05 / Build

Build your site

npx stitch build

The generated dist/ directory is the deployable output. Deploy dist/, not src/. Manual changes to generated files are not durable — always modify src/, then rebuild.

npx stitch build --src src --out dist     # explicit folders
npx stitch build --no-reverse              # clean production output (no markers, no manifest)
npx stitch build --asset-dir .             # non-HTML files at the output root
npx stitch dev                             # build + serve + rebuild on change

By default a build also records what stitch reverse needs and verifies it. Use --no-reverse for the files you actually ship.

Before → after

<header>
  ...
</header>

<stitch src="components/footer.html"></stitch>

<header>
  ...
</header>

<footer>
  ...
</footer>

The browser does not need to understand <stitch>. It receives finished HTML directly with no component-fetching requests and no runtime component parser.

bolt 06 / Dev Server

stitch dev — build, serve, rebuild

npx stitch dev
npx stitch dev --port 8080
npx stitch dev --src website --out public --port 4000 --host 0.0.0.0

Builds your project once, serves the output directory, watches src/ recursively, and rebuilds on every change. Pages that are open in the browser reload by themselves.

What it does

• serves dist/ at http://localhost:3000 (change with --port / --host);
• watches every directory under src/, including ones you create while it runs, and debounces bursts of saves into one rebuild;
• injects a tiny live-reload script into the served HTML only — the files in dist/ stay clean;
• emulates the generated _redirects rules, so routes such as /privacy work locally;
• works for every file type Stitch builds — editing a fragment such as version.txt rebuilds the files that include it.

Errors do not stop the server

A build error — a duplicate id, a missing file, a cycle — is printed in the terminal and the server keeps serving the last good output. Fix the file and save; the next rebuild clears the error.

🔴 STITCH DEV BUILD ERROR
Duplicate stitch id found. Every <stitch id="..."> must be unique:

  id "version" is declared 2 times:
    - src/a/version.txt:1
    - src/b/version.txt:1

terminal 07 / Any Language

Not just HTML — stitch any text file

Stitch directives are plain text, so they work in any text file: .js, .mjs, .css, .c, .h, .py, .txt, .json, .md, and files with no extension at all. Split a file into as many pieces as you like and drag them back together with a tag.

window.DELLUNA_SITE = {
    version:  "<stitch src='version.txt'></stitch>",
    registry: "<stitch src='registry.txt'></stitch>",
    base:     "<stitch src='base.txt'></stitch>"
};

window.DELLUNA_SITE = {
    version:  "v0.0.111",
    registry: "https://cdn.jsdelivr.net/gh/vkdatta/delluna@v0.0.111/registry",
    base:     "https://cdn.jsdelivr.net/gh/vkdatta/delluna@v0.0.111"
};

How it behaves in non-HTML files

• Fragments are not emitted. A file consumed by <stitch src> or $stitch-drop lives inside its consumers, exactly like a consumed HTML component. Only the host is written to dist/.
• Hosts keep their path. src/main.js becomes dist/stitch_assets/main.js, like every other non-HTML file.
• One trailing newline is trimmed from an included text file (and a leading BOM dropped), so the newline your editor adds at the end of version.txt never breaks the string it lands in.
• Includes nest. A fragment may include other fragments, in any language mix: a .js file may include an .html snippet, an HTML page may include a .css or .js file inside <style> / <script>.
• Slots work everywhere. <stitch reusable> with {{slot}} and data-* values is not HTML-specific.
• Only text is stitched. Binary files (images, fonts, archives, anything with NUL bytes or invalid UTF-8) are copied untouched and cannot be included.
• Other text is left alone. In a non-HTML file only tags carrying a Stitch attribute (src, id, reusable, off) are directives. route and loader have no meaning outside HTML and produce a warning.

Building a project that is not a website

By default non-HTML output goes under stitch_assets/. For a C, Python or any other project, emit it at the output root instead:

src/
├── main.c          ← <stitch src="body.c"></stitch>
├── body.c
└── config.h

npx stitch build --src src --out build --asset-dir .

build/
├── main.c          ← composed
└── config.h

body.c was consumed, so it is not emitted. Run your compiler on build/.

tag 08 / id & stitch-drop

Name a file once, drop it anywhere

Give any source file — reusable or not, HTML or not — an id at its head. Then drop it by that name from any other file, without caring where it lives.

<stitch id="version"></stitch>
v0.0.111

window.DELLUNA_SITE = {
    version:  "$stitch-drop('version')",
    registry: "$stitch-drop('registry')",
    base:     "$stitch-drop('base')"
};

window.DELLUNA_SITE = {
    version:  "v0.0.111",
    registry: "https://cdn.jsdelivr.net/gh/vkdatta/delluna@v0.0.111/registry",
    base:     "https://cdn.jsdelivr.net/gh/vkdatta/delluna@v0.0.111"
};

The two forms are equivalent

Pick by path when the file location is the point; pick by id when callers should survive a file being moved or renamed.

Rules

• an id declaration is <stitch id="name"></stitch>; the whole file is what gets dropped;
• when the declaration sits alone on its line, the whole line disappears, so the first line of version.txt does not become a stray blank line;
• the argument may be quoted with ', " or `, or left bare: $stitch-drop(version);
• after the id, data-* values are passed to reusable files, separated by commas or spaces;
• an id is a name without spaces, quotes, parentheses, commas or angle brackets;
• a file declares one id; a tag cannot combine src with id;
• dropped files are fragments: they are not emitted on their own, and they may drop further ids (cycles are a hard error);
• ids work in HTML files too, and are removed from the output like every other declaration.

Duplicate stitch id found. Every <stitch id="..."> must be unique:

  id "version" is declared 2 times:
    - src/a/version.txt:1
    - src/b/version.txt:2

toggle_off 09 / off

off — leave a directive as plain text

Add off to a directive and Stitch ignores it completely: it is not resolved, not stitched, not stripped, and not rewritten — even if the file it names really exists.

<stitch src="location" off></stitch>
<stitch id="version" off></stitch>
$stitch-drop('version', off)

What happens to it

• the text appears in the output exactly as written, including the off attribute;
• it takes no part in the dependency graph, so a missing target is not an error and an off id never collides with a real one;
• it works on every directive: src, id, reusable, route, loader and $stitch-drop;
• off="false", off="0" and off="no" mean not off.

When to use it

• writing documentation about Stitch inside a Stitch project (Markdown, text, source comments);
• switching an include off temporarily without deleting the line;
• a string in your own code that happens to look like a directive.

undo 10 / Reverse

stitch reverse — turn dist back into src

npx stitch build                    # src -> dist (+ dist/.stitch/manifest.json)
npx stitch reverse --src restored   # dist -> restored/   (byte-identical to src)
npx stitch reverse --check          # compare dist's source against ./src, write nothing

Every stitch build records how each output was produced, so the built output can be turned back into the exact source files. This works for HTML and for every other text file Stitch composed.

What a build records

• Markers in built HTML: <!--stitch:begin 12 path/to/part.html-->…<!--stitch:end 12--> around every inlined HTML component, and <!--stitch:drop N--> where a routed target was dropped. Non-HTML files never get markers — a comment in HTML is not a comment in JavaScript or C.
• A manifest at dist/.stitch/manifest.json: the original tags, a lossless patch per transformation (asset-URL rewriting, {{slot}} substitution, tag stripping, inlined text), file modes, and the full content of files that never reach dist/ — orphan components and text fragments such as version.txt.

Options

Guarantees

• every build re-runs the reverse in memory and prints ✔ Reverse check — or lists the files that would not restore identically;
• edits made to built files after the build flow back into the right source file, and Stitch warns when it sees them;
• an edit that destroys generated content is reported as an error instead of silently restoring the wrong text.

recycling 11 / Component Lifecycle

Only consumed components disappear

A file becomes a consumed component when another file references it through <stitch src="..."> or $stitch-drop('id'). Its contents are embedded into the consumer, so that source file is omitted from dist/. This holds for any text file: a version.txt dropped into main.js is not emitted on its own.

Unused HTML files and ordinary assets remain. CSS, JavaScript, images, fonts, manifests, JSON, PDFs, and other files are copied — non-HTML static source files go into dist/stitch_assets/.

lightbulb 12 / Why Stitch

Runtime imports are convenient. Build-time imports are faster.

The problem with runtime composition

A runtime component processor improves source modularity but shifts composition work onto every visitor:

• component HTML may require additional network requests;
• component assembly begins only after the browser starts loading;
• runtime JavaScript must locate and process component tags;
• every visitor repeats the same composition work;
• the deployed website depends on a custom component runtime.

What Stitch gives you

• Easy file management
• Reusable components with build-time data substitution
• Recursive nested composition, in HTML and in any other text file
• Files named by id and dropped anywhere with $stitch-drop
• Lossless stitch reverse and a live stitch dev server
• Fast sites — no component-loader JavaScript shipped to visitors
• Host-native routing via _redirects

Build time may increase slightly because Stitch performs assembly before deployment. That cost happens once per build instead of being paid by every visitor.

SOURCE → ZAP BUILD → DIST → STATIC HOST / CDN → BROWSER

compare 13 / Comparison

How Stitch compares to other approaches

Rough conceptual ranges assuming the network response has already arrived. Network latency can dominate all of these numbers.

* Time to usable page is a rough conceptual range assuming the network response has arrived.

account_tree 14 / Architecture

Current Architecture

Stitch is intentionally a build-time system. Its responsibility ends when the final deployable files have been generated.

src/
│
├── modular HTML files
├── text files in any language (JS, CSS, C, Python, TXT ...)
├── nested directories
├── reusable components, ids
├── routed pages
├── images / fonts / other binary assets
│
▼
ZAP BUILD
│
├── scan every text file for directives
├── validate routes and ids (ids must be unique)
├── build dependency graph (src= and $stitch-drop)
├── detect cycles
├── recursively compose HTML and text files
├── perform data-* substitution
├── strip Stitch directives (except those marked off)
├── emit public HTML pages
├── emit composed text files; consumed fragments are not emitted
├── centralize static assets  →  dist/stitch_assets/
├── rewrite local asset URLs
├── record markers + manifest for stitch reverse
└── generate host routing rules  →  dist/_redirects
│
▼
dist/
│
├── index.html
├── routed HTML files
├── stitch_assets/
├── .stitch/manifest.json  (unless --no-reverse)
├── _redirects  (when routes exist)
└── host configuration files at root
│
▼
STATIC HOST / CDN  →  REAL BROWSER NAVIGATION

What Stitch does not need

• no route runtime;
• no route manifest;
• no client-side page fetcher;
• no body replacement;
• no navigation interception;
• no route cache;
• no transition loader;
• no lazy / JIT route resource system;
• no automatically injected Stitch runtime JavaScript.

code 15 / Tag Reference

Stitch Tag Reference

<stitch src> — File Composition

Instructs Stitch to resolve another local text file — HTML or any other language — and insert its processed contents at the exact position of the tag.

<stitch src="./header"></stitch>
<stitch src="./header.html" />
<stitch src="components/header"></stitch>
<stitch src="data/version.txt"></stitch>     (inside a .js, .css, .c, .py ... file)

<stitch id> — Name a File

Heads any source file with a unique name so other files can drop it without knowing its path. Removed from the output. See id & stitch-drop.

<stitch id="version"></stitch>

$stitch-drop — Include by id

Replaced by the contents of the file declared with that id. Accepts data-* values for reusable files.

$stitch-drop('version')
$stitch-drop("card", data-title="API")

off — Disable a Directive

Any directive carrying off is left in the output exactly as written. See off.

<stitch src="location" off></stitch>
$stitch-drop('version', off)

<stitch reusable> — Reusable Template Declaration

Marks a component as reusable with build-time {{slot}} substitution. The declaration never appears in generated HTML.

<stitch reusable></stitch>

<article>
  <h2>{{title}}</h2>
  <p>{{description}}</p>
</article>

<stitch route> — Public URL Declaration

Declares the public URL for a page. The route does not determine the source file's physical location — a file may exist anywhere inside src/.

<stitch route="/privacy"></stitch>

This declares the public URL https://example.com/privacy.

File name–based routing

Normal HTML files derive routes from their filenames without needing an explicit <stitch route>:

src/index.html       → /
src/terms.html       → /terms
src/docs/index.html  → /docs

Quick command reference

# Install
npm i @vkdatta/stitch -g

# Embed a component (relative or absolute path)
<stitch src="relative or absolute path to file"></stitch>

# File name–based routing
<stitch route="allow"></stitch>

# Explicit route (e.g. inside legal.html)
<stitch route="others/legal"></stitch>

# Name a file, then drop it from anywhere
<stitch id="version"></stitch>
$stitch-drop('version')

# Leave a directive as plain text
<stitch src="location" off></stitch>

# Build, develop, reverse
npx stitch build
npx stitch dev
npx stitch reverse

route 16 / Path Resolution

Component Path Resolution

Stitch resolves component paths relative to the file containing the <stitch src> call, unless the path explicitly indicates the source root. This applies to every file type — a .js, .css or .c file resolves its includes the same way an HTML file does.

Extensions

A directive can point only at a text file. Pointing at an image or any other binary file is a hard error. $stitch-drop('id') needs no path at all: it finds the file by its id.

repeat 17 / Reusable Components

Reusable Components & Data Substitution

Rules

• substitution happens during the build;
• the same component may be consumed multiple times with different values;
• raw component source must not be permanently cached as one rendered result;
• substitution may occur in text or attributes;
• reusable components may consume other components recursively;
• reusable works in any text file, and values can be supplied through $stitch-drop('id', data-name="value") as well as <stitch src>;
• values are inserted literally — characters such as $& or $1 in a value are never treated specially;
• the reusable declaration is removed from output.

fork_right 18 / Routing

Static Host Routing

Routing is a deployment concern, not a browser-side Stitch runtime concern.

How explicit routes work

src/fx/fx_counter.html
  contains: <stitch route="/fx_counter"></stitch>

Stitch emits:
  dist/fx/fx_counter.html

And generates the host rule:
  /fx_counter  /fx/fx_counter.html  200

Result:
  example.com/fx_counter  →  host routing  →  dist/fx/fx_counter.html  →  browser

_redirects generation

When one or more explicit routes exist, Stitch generates dist/_redirects. Each route uses an HTTP 200 rewrite so the visible URL remains the route while the host serves the generated HTML file.

Route validation rules

• an explicit route must begin with /;
• duplicate route values are forbidden (hard error);
• routes are URL paths, not output directories;
• routed files are standalone public pages.

storage 19 / Static Assets

Centralized Asset Output

Non-HTML static source files are copied into a single owned output directory:

src/style.css        →  dist/stitch_assets/style.css
src/script.js        →  dist/stitch_assets/script.js
src/images/logo.svg  →  dist/stitch_assets/images/logo.svg

Text files that use directives are written composed, at the same relative path. Text files consumed by another file are fragments and are not written at all. With --asset-dir . everything lands at the output root instead of stitch_assets/ (for non-web projects).

Asset URL rewriting

Because assets are centralized during the build, Stitch resolves each local asset reference and rewrites the generated URL to the final public asset path.

<link rel="stylesheet" href="../style.css">
  →  <link rel="stylesheet" href="/stitch_assets/style.css">

<img src="../../images/logo.svg">
  →  <img src="/stitch_assets/images/logo.svg">

URL suffix preservation

Query strings and fragments are preserved during rewriting: ../style.css?v=3 → /stitch_assets/style.css?v=3

External URLs not rewritten

URLs beginning with https://, http://, //, data:, javascript:, mailto:, tel:, or a bare #fragment are never modified.

Resource-bearing attributes rewritten

link[href]  script[src]  img[src]  source[src]  video[src]
video[poster]  audio[src]  iframe[src]  embed[src]  object[data]
track[src]  input[src]  srcset

output 20 / Output Rules

What Goes Into dist/

• root src/index.html is emitted as dist/index.html;
• HTML files with explicit <stitch route> are emitted at their mirrored relative locations;
• consumed component files are not emitted as standalone public HTML;
• non-HTML static assets are copied under dist/stitch_assets/ (or the output root with --asset-dir .);
• text files that use <stitch src> / $stitch-drop are emitted composed;
• text files consumed by another file are fragments and are not emitted;
• dist/.stitch/manifest.json is written for stitch reverse unless --no-reverse is used;
• deployment configuration files that must remain at the deployment root are preserved appropriately.

Full example

src/
├── index.html
├── style.css
├── script.js
├── wrangler.toml
├── tags/
│   ├── opening.html
│   └── closing.html
├── pages/
│   ├── privacy.html      ← <stitch route="/privacy">
│   └── support.html
└── fx/
    ├── fx_counter.html   ← <stitch route="/fx_counter">
    └── fx_clamp.html     ← <stitch route="/fx_clamp">

↓ npx stitch build ↓

dist/
├── index.html
├── _redirects
├── wrangler.toml
├── stitch_assets/
│   ├── style.css
│   └── script.js
├── pages/
│   ├── privacy.html
│   └── support.html
└── fx/
    ├── fx_counter.html
    └── fx_clamp.html

error 21 / Validation

Errors & Warnings

Cycle detection

a.html → b.html → c.html → a.html  ← HARD ERROR

Stitch stops and reports the full cycle. Recursive composition has a maximum supported nesting depth of 32. Exceeding the limit fails clearly rather than risking uncontrolled recursion.

inventory_2 22 / Package Structure

Recommended Package Shape

Responsibilities

timeline 23 / Workflow

Developer Workflow

1. Develop in src/

src/
├── modular HTML
├── nested components
├── reusable templates
├── routed pages
├── CSS / JavaScript / images
└── deployment configuration

2. Develop live, then build

npx stitch dev                      # serve + rebuild on every change
npx stitch build --no-reverse       # clean production output

3. Deploy dist/

npx wrangler pages deploy dist

Recover the source from a build

npx stitch reverse --src restored

4. Browser

https://example.com/
https://example.com/privacy
https://example.com/fx_counter

These are normal browser navigations to ordinary static HTML output.

science 24 / Testing

Minimum Regression Tests

Any modification to the build system should test at least:

1. simple component composition;
2. nested component composition;
3. deep recursive component composition;
4. the same component consumed from multiple callers;
5. the same reusable component consumed with different data values;
6. relative component paths;
7. source-root component paths;
8. leading-slash source-root shorthand;
9. missing component errors;
10. circular component errors;
11. path traversal protection;
12. duplicate route errors;
13. invalid route errors;
14. attempted consumption of routed pages;
15. asset copying into stitch_assets/;
16. asset URL rewriting from deeply nested HTML files;
17. query string and fragment preservation during asset rewriting;
18. external URL preservation;
19. wrangler.toml preservation outside stitch_assets/;
20. _redirects generation when routes exist;
21. no <stitch> directives remaining in emitted output;
22. <stitch src> in non-HTML files (JS, CSS, C, Python, TXT), with fragments not emitted;
23. <stitch id> with $stitch-drop, all quoting styles and data-* values;
24. duplicate ids failing with every file and line listed;
25. unknown ids, malformed drops and drop cycles;
26. off leaving directives untouched even when the target exists;
27. text and HTML files including each other without markers leaking;
28. stitch reverse restoring every file byte-for-byte, including edits made to built files;
29. --asset-dir . for non-web output.

block 25 / Hard Rules

What Stitch Never Does

MODULAR SOURCE
+
BUILD-TIME COMPOSITION
+
STATIC OUTPUT
+
HOST-NATIVE ROUTING
=
ZAP