Architecture 🏗️

Stackwright is a typed DSL that compiles YAML into production-ready Next.js applications.

Visual rendering + constrained grammar + AI iteration = non-technical people building enterprise apps that are safe by construction.

The Big Picture

Stackwright transforms your intent into a working app through a predictable pipeline:

text
┌─────────────────────────────────────────────────────────────────────────┐
│                         STACKWRIGHT PIPELINE                            │
└─────────────────────────────────────────────────────────────────────────┘
┌──────────┐      ┌──────────┐      ┌──────────┐      ┌──────────┐
│  YOUR    │      │PREBUILD  │      │  JSON    │      │ NEXT.js  │
│  YAMl    │ ───▶ │          │ ───▶ │  DATA    │ ───▶ │          │
│  FILES   │      │ compiles │      │  (static)│      │  SSG     │
└──────────┘      └──────────┘      └──────────┘      └────┬─────┘
                                                              │
                                                              ▼
                    ┌──────────────────────────────────────────────────────────┐
                    │                        OUTPUT                           │
                    │  ┌──────────┐   ┌──────────┐   ┌──────────┐             │
                    │  │  Static  │   │ Theme    │   │ Typed    │             │
                    │  │  HTML    │ + │ CSS      │ + │ React    │ = 🚀 Fast   │
                    │  └──────────┘   └──────────┘   └──────────┘   Web Apps   │
                    └──────────────────────────────────────────────────────────┘

Data Flow

Here's what happens when you build a Stackwright site:

text
┌─────────────────────────────────────────────────────────────────────┐
│                          REQUEST FLOW                              │
└─────────────────────────────────────────────────────────────────────┘
Browser Request
       │
       ▼
┌─────────────────┐
│   Next.js       │
│   getStaticProps│
└────────┬────────┘
         │
         ▼
┌─────────────────┐
│  JSON Loader    │
│ (no fs needed!) │
└────────┬────────┘
         │
         ▼
┌─────────────────┐
│   Zod Schema    │
│   Validation    │
└────────┬────────┘
         │  Valid? ──▶ Yes ──▶ Continue
         │             │
         │             No ──▶ Build Error (caught early!)
         ▼
┌─────────────────┐
│ ContentRenderer │
└────────┬────────┘
         │
         ▼
┌─────────────────┐
│  ThemeProvider  │
│  (CSS Variables)│
└────────┬────────┘
         │
         ▼
┌─────────────────┐
│  Component      │
│  Registry       │
└────────┬────────┘
         │
         ▼
      HTML 🎉

YAML → JSON Transformation

The prebuild step compiles your YAML into static JSON. Here's what that looks like:

YAML → JSON

yaml
1content:
2  content_items:
3    - type: main
4      label: hero
5      heading:
6        text: "Hello, World!"
7      textBlocks:
8        - text: "Welcome to my site."
9          textSize: body1
10      buttons:
11        - text: "Get Started"
12          href: /getting-started
13          variant: contained
No Runtime Filesystem
The JSON is pre-generated at build time. Next.js serves static files — no fs.readFile at runtime. This makes Stackwright apps compatible with edge functions, CDN hosting, and serverless environments.

Package Architecture

Stackwright is a pnpm monorepo with 10 packages. Here's how they relate:

text
┌─────────────────────────────────────────────────────────────────────────┐
│                        PACKAGE DEPENDENCIES                           │
└─────────────────────────────────────────────────────────────────────────┘
                    ┌─────────────────┐
                    │@stackwright/types│◀── Base: Zod schemas, TypeScript types
                    └────────┬────────┘
                             │
           ┌─────────────────┼─────────────────┬─────────────────┐
           │                 │                 │                 │
           ▼                 ▼                 ▼                 ▼
    ┌─────────────┐  ┌─────────────┐  ┌─────────────┐  ┌─────────────┐
    │  @stackwright│  │  @stackwright│  │  @stackwright│  │  @stackwright│
    │  -core       │  │  -nextjs    │  │  -cli       │  │  -mcp       │
    │             │  │             │  │             │  │             │
    │ Components  │  │ Next.js     │  │ CLI tools   │  │ MCP server  │
    │ Registry    │  │ Adapter     │  │ Validation  │  │ AI tools    │
    └──────┬──────┘  └──────┬──────┘  └──────┬──────┘  └─────────────┘
           │                 │                 │
           │                 │                 │
           ▼                 ▼                 ▼
    ┌─────────────┐  ┌─────────────┐  ┌─────────────┐
    │  @stackwright│  │  @stackwright│  │  @stackwright│
    │  -themes    │  │  -build-    │  │  -icons     │
    │             │  │  -scripts   │  │             │
    │ Theme system│  │ Prebuild    │  │ Lucide icon │
    │ CSS vars    │  │ pipeline    │  │ registry    │
    └─────────────┘  └─────────────┘  └─────────────┘
           │
           ▼
    ┌─────────────┐
    │  @stackwright│
    │  -ui-shadcn  │
    │             │
    │ Radix + Tail│
    └─────────────┘

File Structure

Where everything lives in the monorepo:

text
stackwright/
├── packages/
│   ├── core/                    # YAML→React engine
│   │   └── src/
│   │       ├── components/      # React components
│   │       │   ├── base/        # Content types
│   │       │   ├── structural/  # Layout (PageLayout, NavSidebar)
│   │       │   ├── narrative/   # Carousel, Timeline
│   │       │   └── content/     # Map, etc.
│   │       ├── config/         # Default config
│   │       └── utils/          # Registries, renderers
│   │
│   ├── types/                  # Zod schemas, TypeScript types
│   │   └── src/
│   │       ├── types/          # Content schemas
│   │       └── schemas/         # JSON schemas
│   │
│   ├── nextjs/                 # Next.js adapter
│   │   └── src/components/     # NextImage, NextLink, etc.
│   │
│   ├── themes/                 # Theme system
│   │   └── src/ThemesProvider.tsx
│   │
│   ├── build-scripts/          # Prebuild pipeline
│   │   └── src/
│   │       ├── prebuild.ts     # Main entry
│   │       └── ...             # Transformers
│   │
│   ├── cli/                    # Developer CLI
│   │   └── src/commands/       # init, validate, etc.
│   │
│   ├── mcp/                    # MCP server
│   │   └── src/tools/           # AI authoring tools
│   │
│   ├── icons/                  # Icon registry
│   │   └── src/registry.ts
│   │
│   └── ui-shadcn/              # Radix + Tailwind
│       └── src/components/
│
└── examples/
    └── stackwright-docs/        # This documentation site
        ├── pages/              # YAML page files
        │   ├── index/
        │   ├── getting-started/
        │   ├── content-types/
        │   └── ...
        ├── stackwright.yml     # Theme config
        └── public/
            └── images/         # Co-located images

Package Details

Here's what each package does:

@stackwright/core

**The engine.** YAML→React compilation, component registry, content rendering, hooks, utilities. Exports: `renderContent()`, `stackwrightRegistry`, `registerComponent()`.

@stackwright/types

**The grammar.** Zod schemas for all content types, TypeScript types, JSON schemas for IDE support. The source of truth for what's valid YAML.

@stackwright/nextjs

**The adapter.** Next.js-specific components: `StackwrightImage`, `StackwrightLink`, `createStackwrightNextConfig()`. Handles App Router and Pages Router.

@stackwright/themes

**The skin.** CSS custom properties theming, `ThemeProvider`, `ColorModeScript` for dark mode. Your stackwright.yml colors become CSS variables.

@stackwright/build-scripts

**The compiler.** Prebuild pipeline: YAML→JSON compilation, image copying, search index generation. Runs before `next build` via predev/prebuild hooks.

@stackwright/cli

**The CLI.** `npx launch-stackwright`, `stackwright validate`, `stackwright preview`. Developer interface for scaffolding and testing.

@stackwright/mcp

**The AI bridge.** MCP server exposing content authoring tools, visual rendering preview, git workflow to AI agents. Enables the Otter Raft.

@stackwright/icons

**The icons.** Lucide icon registry. `registerDefaultIcons()` makes all Lucide icons available by name in YAML. Add custom icons the same way.

@stackwright/ui-shadcn

**The components.** Radix UI primitives styled with Tailwind CSS: Accordion, Tabs, Dialog, etc. More flexible than core components for complex UI.

Component Registry

The component registry maps YAML `type` values to React components:

typescript
1// How it works internally:
2 
3// 1. Components register themselves
4export const componentRegistry = {
5  'main': MainContentGrid,
6  'text_block': TextBlockGrid,
7  'carousel': Carousel,
8  'video': Media,
9  'map': Map,
10  // ... 15 more
11};
12 
13// 2. ContentRenderer looks up the type
14function renderContentItem(contentItem) {
15  const Component = componentRegistry[contentItem.type];
16  return <Component {...contentItem} />;
17}
18 
19// 3. You can add custom components
20registerComponent('my-custom-type', MyCustomComponent);
21 
22// 4. YAML maps to component
23// - type: main          → MainContentGrid
24// - type: video         → Media
25// - type: my-custom     → MyCustomComponent (custom!)
Custom Components
Add your own content types with `registerComponent()`. The schema validation and theme system work automatically. The Otter Raft uses this to generate validated YAML.

Safe by Construction

Stackwright's constrained grammar creates a fundamentally different security posture:

Bounded Expressiveness

The Zod schema defines exactly what behaviors are possible. No escape hatch to arbitrary code execution. You audit the framework once — every app is safe.

Build-Time Validation

Every content change is validated against the schema before it reaches the browser. Bad YAML fails the build, not the user.

Auditable Surface Area

Security review reduces to reviewing the component library — a fixed, bounded codebase. Not thousands of YAML files.

Safe AI Generation

When an AI agent generates YAML, it literally cannot express unsafe behavior. The schema is the security policy.

Common Extension Points

Stackwright apps are standard Next.js apps. Extend freely:

Custom Components

Add React components anywhere in the page:

```tsx

// pages/index.tsx

<PageLayout {...props}>

<MyCustomWidget />

</PageLayout>

Custom Content Types

Register new YAML types:

```tsx

registerComponent(

'my-type',

MyComponent

);

Custom Providers

Add React context providers:

```tsx

<MyProvider>

<PageLayout {...props} />

</MyProvider>

Custom Prebuild

Extend the prebuild pipeline:

```ts

// stackwright.yml

prebuild:

hooks:

afterCompile: myTransform

See Also

Now that you understand how it works, start building: