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. Install it globally, then run it inside the project you build and deploy.

folder_open 02 / Structure

Keep your source organized

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

Stitch reads src/ and writes the deployable site to dist/. Static assets are copied into dist/stitch_assets/. HTML files are processed for Stitch imports.

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 HTML file containing the tag. This lets nested HTML files reference components relative to their own location. The referenced HTML may itself contain additional <stitch src> calls — composition is recursive.

Extension handling

When the referenced path has no extension, Stitch appends .html automatically.

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

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. The <stitch reusable> declaration itself never appears in generated HTML.

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.

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.

recycling 06 / Component Lifecycle

Only consumed components disappear

A file becomes a consumed component when another HTML file references it through <stitch src="...">. Its contents are embedded into the consumer, so that source component is omitted from dist/.

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 07 / 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
• 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 08 / 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 09 / 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
├── nested directories
├── reusable components
├── routed pages
├── CSS / JS / images / fonts / other assets
│
▼
ZAP BUILD
│
├── scan HTML files
├── build dependency graph
├── validate routes
├── detect cycles
├── recursively compose HTML
├── perform data-* substitution
├── strip Stitch directives
├── emit public HTML pages
├── centralize static assets  →  dist/stitch_assets/
├── rewrite local asset URLs
└── generate host routing rules  →  dist/_redirects
│
▼
dist/
│
├── index.html
├── routed HTML files
├── stitch_assets/
├── _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 10 / Tag Reference

Stitch Tag Reference

<stitch src> — HTML Composition

Instructs Stitch to resolve another local HTML file 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 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>

# Build
npx stitch build

route 11 / 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.

repeat 12 / 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;
• the reusable declaration is removed from output.

fork_right 13 / 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 14 / 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

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 15 / 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/;
• 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 16 / 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 17 / Package Structure

Recommended Package Shape

Responsibilities

timeline 18 / Workflow

Developer Workflow

1. Develop in src/

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

2. Build

npx stitch build

3. Deploy dist/

npx wrangler pages deploy dist

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 19 / 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 HTML.

block 20 / Hard Rules

What Stitch Never Does

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