PureStack

Build content sites and interactive pages from one coherent source model.

Markdown for your content. TypeScript for your components, styles, and behavior.

Explore the docs · Browse components · See an example site · Contribute

---

Your content. Your components. One pipeline.

PureStack turns a content directory into a static website. Write pages in Markdown or Regor MDX, use built-in components where they help, and add browser-side TypeScript only where a page needs behavior. The CLI handles routes, styles, assets, development preview, and release builds.

PureStack in practice: purestack.studio is built from the frontend source in this repository.

Why coherent source matters

Generating a first page is only the beginning. A product keeps changing: new content, new components, new behavior, and new people working on it.

PureStack's architectural bet is that explicit, typed source makes that ongoing work easier for humans and AI tools to inspect and reason about. Content stays in Markdown; components, style builders, and scripts live in TypeScript. The aim is a source model that remains understandable as the product grows.

.mdx and .rmdx pages use Regor components and expressions. Plain .md files work for prose pages. See the Regor guide for the markup and browser app model.

Get your first page running

1. Create a project

mkdir my-site
cd my-site
npm init -y
npm install purestack
mkdir content

2. Add your config and a page

Your starting point is just two files:

my-site/
└── content/
    ├── siteConfig.json
    └── index.mdx

content/siteConfig.json

{
  "siteTitle": "My Site",
  "logo": { "brand": "My Site", "href": "/" },
  "outDir": "../dist/site",
  "publishDir": "../dist/publish"
}

content/index.mdx

---
title: Welcome
description: My first PureStack site.
template: doc
---

# Make something worth reading.

Start with Markdown. Add components when your page needs more.

<Panel tone="info" variant="surface">
  <p>Your first PureStack page, ready to make your own.</p>
</Panel>

3. Preview it

npx purestack serve --content ./content

Open http://127.0.0.1:4173/. Add content/about.mdx to create /about/. The server watches your files and reloads the browser as you edit.

4. Build for your host

npx purestack build --content ./content
npx purestack publish --content ./content

build writes to dist/site. publish creates a clean, minified artifact in dist/publish; it prepares files for deployment but does not upload them. Both paths come from siteConfig.json and are resolved relative to content.

For browser behavior, add a TypeScript file beside a page and load it with <PageScript src="./example.ts" />. The purestack package README has a complete example.

Pick your next step

I want to…	Start here
Configure a site	Site configuration
Build a richer page	Component catalog
Add browser behavior	PageScript and RegorApp examples
Understand the CLI	CLI guide
Explore a complete project	Sample content · Website source
Work on PureStack itself	Contribution guide

How PureStack fits together

Source	What PureStack does
siteConfig.json	Defines output paths, site identity, themes, navigation, and optional features.
.md, .mdx, .rmdx	Turn content files into routes and HTML pages.
Regor components	Render UI into pages at build time.
PageScript and RegorApp	Bundle TypeScript and add browser behavior where requested.
Static assets	Copies files from the content directory into the site output.

The CLI guide covers the commands and options. Site configuration covers navigation, themes, search, sitemap, localization, and output paths.

Repository map

The workspace contains the CLI, site generator, UI components, typed HTML/CSS builders, browser scripts, icon providers, and a private VS Code extension.

Explore the packages and source directories

Path	Purpose
packages/purestack	Public purestack package, CLI, and TypeScript API.
packages/ts-ssg	Content discovery, rendering, routing, builds, and development server.
packages/ts-components	Built-in UI components and component metadata.
packages/ts-style	Themes, skins, typography, and style generation.
packages/ts-css and packages/ts-html	Typed CSS and HTML builders.
packages/ts-page-scripts	Browser-side behavior used by site components.
packages/ts-svg-icons	SVG icon providers and lookup.
packages/ts-ssg-vscode	Private VS Code extension for PureStack content and components.
frontend	Source for purestack.studio, built with PureStack.
packages/ts-ssg/sample-content	A larger example site with content, components, and browser scripts.

The remaining workspace packages provide shared types, utilities, rendering, and DOM support.

Develop this repository

See Contributing for the branch, pull request, CI, and publishing workflow.

Use Node.js 24 and the Yarn version pinned in package.json. Run commands from the repository root:

corepack enable
yarn install --immutable
yarn build
yarn dev

yarn dev serves the included sample site. To work on the PureStack website, run yarn frontend; its development server opens at http://127.0.0.1:4700/. See the frontend README for the site-specific workflow.

Command	Purpose
yarn lint:ci	Check source without modifying files.
yarn test:ci	Run the test suite once.
yarn bundle	Build distributable packages.
yarn package	Pack non-private workspaces into local tarballs.

---

Build something with PureStack. Help shape what comes next.

Documentation · Report a bug · Contribute

Released under the MIT license.