| name | apprun-skills |
| description | End-to-end guidance for AppRun apps in TypeScript using MVU including component patterns, event handling, state management (including async generators), routing/navigation with params and guards, and testing with vitest. Use when designing or reviewing AppRun components, wiring routes, managing state flows, or writing AppRun tests. |
AppRun Skills
Overview
- Build AppRun apps with MVU (Model-View-Update) in TypeScript.
- Prefer pure update functions for testability.
- Use
mounted() for components embedded in JSX.
- Use
state = async only for top-level routed pages that must load async data.
Project Setup
Recommended Project Structure
web/ # Frontend application root
├── index.html # Entry HTML file
├── package.json # Dependencies and scripts
├── vite.config.js # Vite configuration
├── src/
│ ├── main.tsx # Application entry point (routes registration)
│ ├── api.ts # REST API client (optional)
│ ├── styles.css # Application styles
│ ├── tsconfig.json # TypeScript configuration
│ ├── components/ # Reusable UI components
│ │ ├── Layout.tsx # Root layout container
│ │ └── ... # Other reusable components
│ ├── domain/ # Business logic modules (optional)
│ │ └── ... # Pure functions and business logic
│ ├── pages/ # Top-level page components
│ │ ├── Home.tsx # Example: Home page
│ │ └── ... # Other route pages
│ ├── types/ # TypeScript type definitions
│ │ ├── index.ts # Shared types
│ │ └── jsx.d.ts # JSX type declarations
│ └── utils/ # Utility functions
└── public/ # Static assets (optional)
Vite Configuration
import { defineConfig } from 'vite'
export default defineConfig({
build: {
outDir: 'dist',
emptyOutDir: true,
},
server: {
port: 8080,
open: true,
historyApiFallback: true,
proxy: {
'/api': {
target: 'http://127.0.0.1:3000',
changeOrigin: true,
secure: false
}
}
}
})
Package.json
{
"name": "my-apprun-app",
"version": "1.0.0",
"type": "module",
"scripts": {
"dev": "vite",
"build": "vite build",
"preview": "vite preview",
"check": "tsc --noEmit"
},
"devDependencies": {
"apprun": "^3.38.0",
"typescript": "^5.0.0",
"vite": "^5.0.0"
}
}
TypeScript Configuration
{
"compilerOptions": {
"target": "ES2020",
"module": "ESNext",
"lib": ["ES2020", "DOM", "DOM.Iterable"],
"jsx": "react",
"jsxFactory": "app.createElement",
"jsxFragmentFactory": "app.Fragment",
"moduleResolution": "bundler",
"resolveJsonModule": true,
"isolatedModules": true,
"strict": true,
"esModuleInterop": true,
"skipLibCheck"
Critical Settings for AppRun:
jsx: "react" - Enables JSX syntaxjsxFactory: "app.createElement" - Uses AppRun's JSX factoryjsxFragmentFactory: "app.Fragment" - Uses AppRun's Fragment supportmoduleResolution: "bundler" - Optimized for Vite
Entry Points
HTML Entry (index.html):
<!DOCTYPE html>
<html lang="en">
<head>
<meta charset="UTF-8">
<meta name="viewport" content="width=device-width, initial-scale=1.0">
<title>My AppRun App</title>
</head>
<body>
<div id="root"></div>
<script type="module" src="src/main.tsx"></script>
</body>
</html>
Application Entry (src/main.tsx):
import app from 'apprun';
import Layout from './components/Layout';
import Home from './pages/Home';
import About from './pages/About';
import './styles.css';
app.render('#root', <Layout />);
app.addComponents('#pages', {
'/': Home,
'/about': About,
});
Layout Component (src/components/Layout.tsx):
import app from 'apprun';
export default () => (
<div id="app">
<div id="pages"></div>
</div>
);
Styling Options
Option 1: Vanilla CSS
:root {
--color-primary: #007bff;
--color-text: #333;
--spacing-unit: 8px;
}
body {
font-family: system-ui, -apple-system, sans-serif;
color: var(--color-text);
margin: 0;
padding: 0;
}
Option 2: Tailwind CSS v4
Install Tailwind v4:
npm install -D tailwindcss@next @tailwindcss/vite@next
Update vite.config.js:
import { defineConfig } from 'vite'
import tailwindcss from '@tailwindcss/vite'
export default defineConfig({
plugins: [tailwindcss()],
})
Import in src/styles.css:
@import "tailwindcss";
Use in components:
<div className="flex items-center gap-4 p-4 bg-white rounded-lg shadow">
<h1 className="text-2xl font-bold">Hello World</h1>
</div>
Option 3: CSS Modules
import styles from './MyComponent.module.css';
export default () => (
<div className={styles.container}>
<h1 className={styles.title}>Hello</h1>
</div>
);
API Client Pattern
const API_BASE_URL = '/api';
interface RequestOptions extends RequestInit {
params?: Record<string, string>;
}
async function request<T>(
endpoint: string,
options: RequestOptions = {}
): Promise<T> {
const { params, ...fetchOptions } = options;
let url = `${API_BASE_URL}${endpoint}`;
if (params) {
const query = new URLSearchParams(params).toString();
url += `?${query}`;
}
const response = await fetch(url, {
headers: {
'Content-Type': 'application/json',
...fetchOptions.headers,
},
...fetchOptions,
});
if (!response.ok) {
const error = await response.json().catch(() => ({}));
throw new Error(error.message || `HTTP `);
}
response.();
}
api = {
: <T>
request<T>(endpoint, { : , params }),
: <T>
request<T>(endpoint, {
: ,
: .(data),
}),
: <T>
request<T>(endpoint, {
: ,
: .(data),
}),
: <T>
request<T>(endpoint, { : }),
};
api;
Quick Start
npm create vite@latest my-apprun-app -- --template vanilla-ts
cd my-apprun-app
npm install
npm install -D apprun
mv src/main.ts src/main.tsx
npm run dev
npm run build
npm run preview
Why Vite + AppRun?
Why Vite:
- Fast development with instant HMR
- Optimized builds with Rollup
- First-class TypeScript support
- Minimal configuration
Why AppRun:
- Lightweight (~7KB gzipped)
- Simple MVU pattern
- Direct DOM updates (no virtual DOM)
- Full TypeScript support
- Built-in routing
Component Patterns - Decision Tree
- Manages state + user interactions? → Stateful Class Component
- Popup/modal/overlay? → Modal Component (use
mounted())
- Display-only from props? → Functional Component
- 10+ events needing type safety? → Typed Events Pattern
Stateful Class Component
Structure Order: Imports → Interfaces → Helpers → Actions → Component
import { app, Component } from 'apprun';
interface Props { data?: any; }
export interface State {
loading: boolean;
error: string | null;
successMessage?: string;
}
const getStateFromProps = (props: Props): State => ({ });
export const saveData = async function* (state: State): AsyncGenerator<State> {
if (!state.data.name.trim()) {
yield { ...state, error: 'Name required' };
return;
}
yield { ...state, loading: true, error: null };
try {
await api.save(state.data);
{ ...state, : , : };
app.();
} (: ) {
{ ...state, : , : error. };
}
};
<> {
: <>;
mounted = (: ): (props);
view = {
(state.) ;
(state.) ;
(
);
};
}
View Pattern: Guard clauses → Early returns → Main content
Modal Component
CRITICAL: Must use mounted() (embedded in JSX), not state = async
export default class Modal extends Component<State> {
declare props: Readonly<Props>;
mounted = (props: Props): State => getStateFromProps(props);
view = (state: State) => (
<div className="modal-backdrop" onclick={closeModal}>
<div className="modal-content" onclick={(e) => e.stopPropagation()}>
<button onclick={closeModal}>×</button>
{/* content */}
</div>
</div>
);
}
Requirements: Close button + backdrop click + stopPropagation
Functional Component
export interface Props {
data: DataType[];
onItemClick?: (item: DataType) => void;
}
export default function DisplayComponent({ data, onItemClick }: Props) {
if (!data?.length) return <div>No items</div>;
return (
<ul>
{data.map(item => (
<li onclick={() => onItemClick?.(item)}>{item.name}</li>
))}
</ul>
);
}
Pattern: Destructure → Guard clauses → Main render
Typed Events Pattern
Payload Rules:
- Single value →
payload: string | Call: $onclick={['delete', id]}
- Multiple values →
payload: { id: string; name: string } | Call: $onclick={['edit', { id, name }]}
- No payload →
payload: void | Call: $onclick="save"
- Input events →
payload: { target: { value: string } }
export type MyEvents =
| { name: 'save'; payload: void }
| { name: 'delete'; payload: string }
| { name: 'edit'; payload: { id: string; name: string } };
export type MyEventName = MyEvents['name'];
class MyComponent extends Component<State, MyEventName> {
override update = myHandlers;
}
export const myHandlers: Update<State, MyEventName> = {
save: (state): State => ({ ...state, saved: true }),
delete: (state, id: string): State => ({
...state,
items: state.items.filter(i => i. !== id)
}),
: (state, { id, name }: { : ; : }): ({
...state,
: { id, name }
})
};
stopPropagation: Add event as last parameter
'click-item': (state, id: string, e?: Event): State => {
e?.stopPropagation();
return { ...state, selected: id };
}
Event Directives
AppRun Directives (Trigger Update Handlers)
| Directive | Use Case | Example |
|---|
$bind="field" | Two-way binding (PREFERRED for forms) | <input $bind="name" /> |
$bind="nested.field" | Nested property | <input $bind="user.profile.name" /> |
$onclick="action" | String action | <button $onclick="save" /> |
$onclick={['action', data]} | Action with params | <button $onclick={['delete', id]} /> |
$onclick={[func]} | Direct function | <button $onclick={[saveData]} /> |
$oninput="handler" | Custom input handling | <input $oninput="validate" /> |
Other directives: $onchange, $onsubmit, $onfocus, $onblur, $onkeydown
Standard HTML Events (DOM Manipulation)
Use onclick, oninput, etc. for direct DOM manipulation only:
<div onclick={(e) => e.stopPropagation()}>Content</div>
When to Use What
- ✅
$bind - Simple form fields (no handler needed)
- ✅
$oninput - Validation, transformation, debouncing
- ✅
$onclick - Trigger update handlers
- ❌ Never -
$onclick={() => app.run('action')}
Validation Example:
$oninput="validate-email"
'validate-email': (state, e: Event) => {
const email = (e.target as HTMLInputElement).value;
const valid = /^[^\s@]+@[^\s@]+\.[^\s@]+$/.test(email);
return { ...state, email, emailError: valid ? null : 'Invalid' };
}
Update Handlers
Sync: Return new state
'increment': (state) => ({ ...state, count: state.count + 1 })
Async: Use async
'load': async (state) => {
this.setState({ ...state, loading: true });
const data = await api.fetch();
return { ...state, data, loading: false };
}
Generator: Multi-step with intermediate renders (PREFERRED for complex flows)
'save': async function* (state) {
yield { ...state, loading: true };
await api.save(state.data);
yield { ...state, loading: false, success: true };
}
Side Effects: No return = no re-render
'navigate': (state) => {
window.location.href = '/path';
}
Component Communication
| Pattern | Use Case | Implementation |
|---|
| Props | Parent → Child | Pass data via props |
| Callbacks | Child → Parent | Pass function via props |
| Global Events | Any → Any | is_global_event = () => true |
Global Events:
class Modal extends Component {
is_global_event = () => true;
update = {
'open-modal': (state, data) => ({ ...state, visible: true, data }),
'close-modal': (state) => ({ ...state, visible: false })
};
}
<button onclick={() => app.run('open-modal', data)}>Open</button>
Critical Rules
State Initialization
| Component Type | Use | Example |
|---|
| JSX Embedded | mounted() | mounted = (props) => getStateFromProps(props) |
| Top-Level Routed | state = async | state = async () => { const data = await api.fetch(); return { data }; } |
❌ NEVER mix both mounted() and state = async
State Updates
Returning state triggers re-render:
- Immutable (recommended):
return { ...state, field: value }
- Mutable (allowed):
state.field = value; return state
- Side effects only: Don't return (no re-render)
Required State Properties
interface State {
loading: boolean;
error: string | null;
successMessage?: string;
}
Deep Cloning
return {
...state,
user: {
...state.user,
profile: {
...state.user.profile,
name
}
}
};
Anti-Patterns
❌ DON'T:
$onclick={() => app.run('action')}
async function save() { await api.save(); }
$oninput={(e) => setState({ ...state, field: e.target.value })}
class Modal extends Component {
state = async () => { };
}
messages.map()
update = [['event', handler]]
state.count++;
Routing, Linking, and Component Registration
This section explains how AppRun applications handle routing, page navigation, and component registration.
Overview
The app uses AppRun's built-in routing system without any external router libraries. Routes are defined declaratively, and navigation uses standard HTML anchor tags or programmatic methods.
1. Component Registration
Routes are registered centrally in main.tsx:
import app from 'apprun';
import Layout from './components/Layout';
import Home from './pages/Home';
import World from './pages/World';
app.render('#root', <Layout />);
app.addComponents('#pages', {
'/': Home,
'/World': World,
});
How It Works:
app.render('#root', <Layout />): Renders the top-level Layout component into the #root DOM elementapp.addComponents('#pages', {...}): Registers route-to-component mappings
- Key: Route path (e.g.,
'/', '/World')
- Value: Component class (e.g.,
Home, World)
- Components are rendered into the
#pages container defined in Layout
2. Layout Container
The Layout component provides the rendering container for routed pages:
export default () => <div id="main" className="w-full min-h-screen">
<div id="pages"></div>
</div>
- Minimal wrapper with full-width, full-height container
- The
#pages div is where route components are dynamically rendered
- AppRun automatically swaps components based on the current route
3. Page Linking (Declarative Navigation)
The app uses standard HTML anchor tags for navigation:
Example from Home Component:
<a href={'/World/' + worldName}>
<button className="btn btn-primary">
Enter {worldName}
</button>
</a>
Example from World Component:
<a href="/">
<button className="back-button" title="Back to Worlds">
<span className="world-back-icon">←</span>
</button>
</a>
How It Works:
- Standard
<a href=""> links trigger AppRun's routing
- AppRun intercepts link clicks and updates the route without full page reload
- Route parameters (like world name) are included in the URL path
- No special Link component required—just plain HTML
4. Programmatic Navigation
Components can navigate programmatically using window.location.href:
Example from Home Component Update Handler:
update = {
'enter-world': (state: HomeState, world: World): void => {
window.location.href = '/World/' + world.name;
}
}
When to Use:
- Inside event handlers that need to navigate after logic
- When navigation is a side effect (return
void instead of new state)
- For conditional navigation based on user actions
5. Route Parameters
Routes can include dynamic parameters in the path:
URL Pattern:
/World/:worldName
Parsing Parameters:
Components can access route parameters from the URL:
const worldName = window.location.pathname.split('/')[2];
Route Handler Pattern:
update = {
'/World': async (state, worldName: string) => {
return {
...state,
worldName,
};
}
}
6. Component Architecture (MVU Pattern)
Page components follow AppRun's Model-View-Update pattern:
export default class PageComponent extends Component<StateType> {
state = {
loading: true,
data: null,
};
view = (state: StateType) => {
return <div>
{/* JSX markup */}
</div>;
};
update = {
'event-name': (state, payload) => {
return { ...state, newData: payload };
},
'navigation-event': (state) => {
window.location.href = '/path';
}
};
}
Key Principles:
- State: Plain object with component data
- View: Pure function that converts state to JSX
- Update: Event handlers that return new state or void
- Immutability: Always return new state objects, never mutate
7. Event System
Local vs Global Events:
Components can be configured to listen to global events:
export default class WorldComponent extends Component {
override is_global_event = () => true;
}
Event Propagation:
- Local events: Only visible within the component
- Global events: Can be triggered from child components or other parts of the app
- Use
app.run('event-name', payload) to trigger events programmatically
Event Handler Types:
update = {
'update-data': (state, newData) => ({
...state,
data: newData
}),
'navigate': (state) => {
window.location.href = '/path';
}
}
8. Best Practices
Navigation:
- ✅ Use
<a href=""> for simple links
- ✅ Use
window.location.href for programmatic navigation
- ✅ Include route parameters in the path:
/World/${name}
- ❌ Don't use client-side routing for external URLs
Component Registration:
- ✅ Register all routes in a single place (
main.tsx)
- ✅ Use clear, semantic route paths
- ✅ Keep the route structure flat and simple
- ❌ Don't nest routes deeply
Event Handling:
- ✅ Return new state to trigger re-render
- ✅ Return void for navigation or side effects
- ✅ Use descriptive event names:
'load-world', 'delete-chat'
- ❌ Don't mutate state directly
URL Structure:
/ → Home page (world selection)
/World/:name → World page (chat interface)
/Agent/:id → Agent page (currently disabled)
/Settings → Settings page (currently disabled)
9. Example Flow: Entering a World
Step 1: User clicks "Enter World" button on Home page
<a href={'/World/' + world.name}>
<button className="btn btn-primary">
Enter {world.name}
</button>
</a>
Step 2: AppRun intercepts the link and updates route
- URL changes to
/World/MyWorld
- AppRun's router detects the route change
- Router looks up the registered component for
/World
Step 3: World component is mounted and initialized
update = {
'/World': async (state, worldName: string) => {
const world = await api.getWorld(worldName);
const messages = await api.getMessages(worldName);
return {
...state,
worldName,
world,
messages,
loading: false
};
}
}
Step 4: World component renders with loaded data
- View function receives the updated state
- Chat interface displays with agents and messages
- Component is now interactive and listening for events
10. Debugging Tips
Check Current Route:
console.log(window.location.pathname);
Monitor Route Changes:
app.on('//', (route) => {
console.log('Route changed to:', route);
});
Verify Component Registration:
console.log(document.querySelector('#pages').innerHTML);
Summary
- Registration:
app.addComponents('#pages', { path: Component })
- Navigation: Use
<a href=""> or window.location.href
- Route Params: Parsed from URL path in route handlers
- Component Pattern: MVU (Model-View-Update)
- Events: Local by default, can be made global with
is_global_event()
- No Router Library: AppRun's built-in routing handles everything
Testing (Vitest)
- Unit test pure update functions.
- Iterate async generators to capture each yield.
- Mock APIs with
vi.mock.
import { describe, it, expect, vi } from 'vitest';
import { save } from './Form';
import api from '../api';
vi.mock('../api');
describe('save', () => {
it('yields validation then stops', async () => {
const state = { loading: false, error: null, form: { name: '' } } as State;
const gen = save(state);
const first = await gen.next();
expect(first.value?.error).toBe('Name is required');
});
});
Development Checklist
Component Structure
TypeScript Types
View Method
State Management
Event Handling
Error Handling
Best Practices
Quick Reference
Component Selection:
- State + interactions → Stateful Class
- Modal/popup → Modal Component (
mounted())
- Display only → Functional
- 10+ events → Typed Events
State Init:
- JSX embedded →
mounted()
- Routed page →
state = async
Events:
$bind for forms (preferred)$onclick for actions- Typed for large components
Updates:
- Return state → re-render
- No return → side effect
- Generators → multi-step
Communication:
- Props: parent → child
- Callbacks: child → parent
- Global: any → any
