AppRun

⭐ NEW instruction: Step-by-step guide to building a Single Page Application (SPA) using the AppRun pattern, with architectural reasoning for each step:

• Building a SPA Using AppRun.

🕵️ We also have rule / prompt files that you can use with your AI Coding Agent:

• For Components using JSX

🚀 July 2025, We have started to improve the codebase using AI - the spec-driven flow. The requirements, implementation plan and final results are stored in the docs folder.

Introduction

AppRun is a lightweight framework for building web apps. It has a unique architecture inspired by the Elm architecture that can help you manage states, routing, and other essential aspects of your web application, leveraging the power of the event publish-subscribe pattern.

AppRun Benefits

• Clean architecture that needs minimal setup and boilerplate code.
• Decoupled architecture that is test friendly.
• No proprietary syntax to learn (no hooks, no reducers, no signals)
• State management and routing included
• Use directly in the browser or with a compiler/bundler
• Advanced features: JSX, Web Components, Dev Tools, SSR, etc.

Examples

Let's use a Counter as an example to demonstrate the AppRun architecture:

// define the initial state
const state = 0;

// view is a function to display the state (JSX)
const view = state => <div>
  <h1>{state}</h1>
  <button onclick="app.run('-1')">-1</button>
  <button onclick="app.run('+1')">+1</button>
</div>;

// update is a collection of event handlers
const update = {
  '+1': state => state + 1,
  '-1': state => state - 1
};

// start the app
app.start(document.body, state, view, update);

With directives syntax sugar you can write more concise code:

// define the initial state
const state = 0;

// view is a function to display the state (JSX)
const view = state => <div>
  <h1>{state}</h1>
  <button $onclick="-1">-1</button>
  <button $onclick="+1">+1</button>
</div>;

// update is a collection of event handlers
const update = {
  '+1': state => state + 1,
  '-1': state => state - 1
};

// start the app
app.start(document.body, state, view, update);

Alternatively, you can invoke state update functions without events for local state updates:

// define the initial state
const state = 0;

// state update function
const add = (state, value) => state + value;

// view is a function to display the state (JSX)
const view = state => <div>
  <h1>{state}</h1>
  <button $onclick={[add, -1]}>-1</button>
  <button $onclick={[add, 1]}>+1</button>
</div>;

// start the app
app.start(document.body, state, view);

One cool feature of AppRun is that you can use async generator functions for event handlers to return multiple values. AppRun will render each value in the order they are generated.

const state = {};
const view = state => html`
  <div><button @click=${run(getComic)}>fetch ...</button></div>
  ${state.loading && html`<div>loading ... </div>`}
  ${state.comic && html`<img src=${state.comic.img} />`}
`;
async function* getComic() {  // async generator function returns loading flag and then the comic object
  yield { loading: true };
  const response = await fetch('https://xkcd-api.netlify.app');
  const comic = await response.json();
  yield { comic };
}

app.start(document.body, state, view);

And, of course, you can use Components to encapsulate the logic blocks, e.g., SPA pages. Each component can have its own state, view, and update functions. Each component has its own handlers to handle the routing events. AppRun routes /<path>, #<path>, and #/<path> URLs to components. AppRun also does this with hierarchical routing.

class Home extends Component {
  view = () => <div>Home</div>;
  update = {'/, /home': state => state };
}

class Contact extends Component {
  view = () => <div>Contact</div>;
  update = {'/contact': state => state };
}

class About extends Component {
  view = () => <div>About</div>;
  update = {'/about': state => state };
}

const App = () => <>
  <div id="menus">
    <a href="/home">Home</a>{' | '}
    <a href="/contact">Contact</a>{' | '}
    <a href="/about">About</a></div>
  <div id="pages"></div>
</>

app.render(document.body, <App />);
[About, Contact, Home].map(C => new C().start('pages'));

Finally, you can use AppRun with React. The app.use_react function allows you to use React for rendering the view.

import React from 'react'
import ReactDOM from 'react-dom/client'
import app from 'apprun';
use_react(React, ReactDOM);

The app.use_render function allows you to use a other render library for rendering the view. Enjoy the rich ecosystem of React.

import { render } from 'preact'
import app from 'apprun';
app.use_render(render);

There are many more examples and interactive demos available in the AppRun Playground.

Getting Started

AppRun is distributed on npm. To get it, run:

npm install apprun

When you want to do a rapid prototyping or demo, you can use AppRun directly in the browser without JSX or any build step. The app, html and run functions are available globally. The html is a HTML template from lit-html. The run function is a equivalent to the $on directive, which can be used to invoke state update functions.

<html>
<body>
<script src="https://unpkg.com/apprun/dist/apprun-html.js"></script>
<script>
  const add = (state, delta) => state + delta;
  const view = state => {
    return html`<div>
    <h1>${state}</h1>
      <button @click=${run(add, -1)}>-1</button>
      <button @click=${run(add, +1)}>+1</button>
    </div>`;
  };
  app.start(document.body, 0, view);
</script>
</body>
</html>

Or, use the ESM version:

<html>
<body>
<script type="module">
  import { app, html } from 'https://unpkg.com/apprun/dist/apprun-html.esm.js';
  const view = state => html`<div>${state}</div>`;
  app.start(document.body, 'hello ESM', view);
</script>
</body>
</html>

In addition to run directly in the browser, you can run the npm create apprun-app command to create an AppRun project for using a compiler/bundler like Webpack, esbuild or Vite.

npm create apprun-app [my-app]

Learn More

You can read AppRun Docs.

AppRun Book from Apress

• Order from Amazon

Contribute

You can launch the webpack dev-server and the demo app from the demo folder with the following npm commands:

npm install
npm start

You can run the unit tests from the tests folder.

npm test

Unit tests can serve as functional specifications.

Finally, to build optimized js files to the dist folder, just run:

npm run build

Have fun and send pull requests.

Contributors

Support

AppRun is an MIT-licensed open-source project. Please consider supporting the project on Patreon. 👍❤️🙏

Thank you for your support

• Athkahden Asura
• Alfred Nerstu
• Gyuri Lajos
• Lorenz Glißmann
• Kevin Shi
• Chancy Kennedy

License

MIT

Copyright (c) 2015-2025 Yiyi Sun