DEV Community: yysun

Bringing the LLM Wiki Idea to a Codebase

yysun — Sun, 12 Apr 2026 20:43:09 +0000

Andrej Karpathy’s LLM Wiki idea is compelling because it treats knowledge as something that can be gradually ingested, organized, queried, and improved over time. That same idea applies surprisingly well to a codebase.

A repository is not just a pile of files. It is a living body of knowledge: architecture, concepts, flows, conventions, tradeoffs, and accumulated decisions. The challenge is that this knowledge is often scattered across source files, configs, docs, and human memory. A wiki built for an LLM can help turn that into something navigable.

For code projects, the core ideas of ingest, query, and lint still hold:

Ingest builds and updates the project wiki from the source
Query uses the wiki plus source verification to answer questions about the codebase
Lint checks the wiki itself for drift, contradictions, missing coverage, and weak links

That already makes the LLM Wiki concept useful for software projects. But codebases have one advantage that many other knowledge collections do not: git.

Why codebases are a particularly good fit

Most project knowledge systems either rescan everything every time or rely on manual upkeep. A codebase, however, already has built-in version control. That gives us a natural way to make wiki maintenance incremental.

The initial ingest can be based on the repository at HEAD. After that, the wiki records the last ingested commit. Future ingests do not need to rescan the whole repo. They only need to look at what changed between that saved commit and the new HEAD.

That means git gives us, almost for free:

changed-file detection
rename and deletion tracking
a natural checkpoint for incremental updates
a practical way to mark stale wiki pages
a much cheaper ingest loop over time

So the wiki stays grounded in the current codebase, while git provides the mechanism for maintaining it efficiently.

The model

The model is simple:

Ingest the project from HEAD
Save the current commit SHA in the wiki index
On the next run, diff from last_commit to HEAD
Update only the affected pages
Advance the checkpoint only when the changed set has been fully processed

This keeps HEAD as the source of truth while using git history as the maintenance engine.

That distinction matters. The wiki is not meant to become a commit log or historical archive. Its main job is to explain the project as it exists now. Git just makes it possible to keep that explanation fresh without starting from scratch every time. The uploaded skill draft reflects exactly that approach: source of truth is git-tracked files at HEAD, while incremental ingest is driven by the saved last_commit.

What the wiki should do

A code-project wiki is most useful when it acts as a structured knowledge layer over the repository.

It should capture things like:

major features and modules
important concepts and abstractions
entities such as schemas, models, and types
request or execution flows
notable fixes and architecture shifts
open gaps and stale areas worth revisiting

From there, the three core workflows, ingest, query and lint become very natural.

That is where the LLM Wiki idea becomes more than passive documentation. It becomes an active system for maintaining project understanding.

The agent skill

I packaged this idea as an agent skill:

npx skills add yysun/awesome-agent-world --skill git-wiki

The goal is to make the pattern reusable: ingest the codebase once, keep a wiki under .wiki, and then let the agent maintain it incrementally as the project evolves.

Closing thought

What makes the LLM Wiki idea powerful is not just that it produces summaries. It creates a feedback loop between source material, structured knowledge, and future questions.

For a codebase, that loop is even stronger because git gives us a built-in notion of change. Instead of rebuilding understanding from scratch, we can carry it forward commit by commit.

That is the real opportunity here: treat the repository not just as code, but as a knowledge system with memory, structure, and maintenance built in.

Effective Agent Instruction

yysun — Wed, 25 Jun 2025 18:08:20 +0000

Introduction

You would think AI coding is simply tell the coding agent what you want, and then you can sit back and enjoy the work AI has accomplished. Wrong! Often you return to find a thousand commits that have completely ruined your codebase, and far from your original intention.

This is the reality of AI coding. The coding agent does not understand your requirements unless you provide them clearly. The agent will follow your instructions to the letter, but if those instructions are vague or incorrect, the results will be far from what you expected.

In this article, I will share my experience of using AI coding agents like GitHub Copilot create a Statement of Work (SOW) between you and the coding agent. This SOW approach will ensure that the agent delivers what you want, rather than what it thinks you want.

Here is the workflow I have been using to create a SOW with AI coding agents.

Define the Requirements: I describe my requirements. No need to be robust. I let AI create the document for me with prompts like:"focus on what, not how, not optimization". Once I have the requirement doc, I will ask AI to verify it: "Review requirements → think hard ensure no flaw → provide suggestions → wait for confirmation."
Implementation Plan: Once both AI and I are happy with the requirement doc, I will ask AI to create an implementation: "Create a implementation plan → save to docs/plan/plan-{name}.md → wait for confirmation."
Tests and Acceptance Criteria: A good new is that AI usually creates the test scenrios and acceptance criteria automatically. I do a final review and approve AI to proceed with the implementation.

You can see are many repeaititive steps in the process of typing same prompts again and again. To make it easier, I have created a set of command aliasin in CLAUDE.md for Claude Code. Or in copilot-ininstructions.md for GitHub Copilot.

Command Alias

I have the following as the custom prompt to the coding agent:

## Command Keywords
- **!!**: Create requirements → focus on `what`, not `how`, no plan → save to `docs/requirements/req-{name}.md` → wait for confirmation;
- **AA**: Create a detailed functional implementation plan (no optimization) as check list → save the list to `docs/plan/plan-{name}.md` → wait for confirmation;
- **AP**: Review requirements → think hard ensure no flaw → provide suggestions → wait for confirmation;
- **AS**: Execute plan → implement step-by-step → mark done in plan → git stage changed and commit;
- **!!!**: Update the requirements, plan, and implement;

2. Workflow

I usually following the steps below:

I describe ideas and !! to create a requirement document.

When requirements are ready, I use a lot AP, AP, AP … to review and confirm the requirements.

Then, I use AA to create an implementation plan. AI analyzes the current code base and identifies what needs to be change.

Do not rush to implement yet. Use AP again and again to ensure the plan is right. You will be supprized.

Only when we are cool with plan, I will use AS to let AI start implementation.

Now, AI takes over and write code step by step.

If I changed my mind, I can always use !!! to update the requirements, plan, and implementation. AI will re-evaluate the plan and code accordingly.

After all, this approach will ensure the source code to have better chance to meet our requirements.

We will also have good the requirement and execution result documentation.The documents are extremely important. We can use for analysis, verification and even reimplement in the future. They are the true source code.

3. One More Thing

The approach above applies to all coding agents. It does not require the code agents to provide facilitates on things like design mode, ask mode, act mode, and etc. Just use plain old prompts, the LLM is smart enough to understand the command alias to execute the workflow including when to start to code.

It worked very well for me in the GitHub Copilot Agent Mode with Claude Sonnet 3/4. Not so well with GPT and Gemini though.

4. Conclusion

The coding paradigm is shifting, from vibe coding to effective agent instruction. By creating a SOW between you and the coding agent, you can ensure the agent will deliver what you want. By using the command alias, you can speed up the process and concentrate on the requirements and implementation plan, rather than the typing prompts again and again.

BTW, Here is Github repository that contains the command alias collage-cli

Happy coding with AI!

AI-Powered Documentation: Make Your Codebase Self-Explanatory

yysun — Fri, 06 Jun 2025 22:18:42 +0000

Introduction

Andrej Karpathy recently introduced the idea of "vibe coding" on X (formerly Twitter), which is a process where we develop apps but "forget that the code even exists". I believe in this approach, but I also have a fundamental need: code understanding: what AI has executed; does it fulfill requirements, and is it safe?

Through documentation can solve the problem. Imagine opening a project, you will see a docs folder that has the architecture, features, and changes documents. And each source code file contains a comment block about what it is for, how it works. These documents can help us understand the code base better.

However, documentation is a difficult task. In fact, according to the Agile practices, due to time constraints, comprehensive documentation is sometimes sacrificed in favor of rapid coding and delivery. Can we even expect having up-to-date documents?

Well, the good news is that AI can do the documentation tasks. In this post, we’ll explore two powerful prompts you can ask AI to do the documentation.

1. Describe Each Source File

Prompt:

Ensure each source file begins with a comment block summarizing its purpose and logic.
- If no block exists, create one before editing.
- After completing changes, update this block to reflect the changes.
- Always make the comment block clear and concise.

Benefits:

This prompt will add a comment block to source code files summarizing its purpose and logic.

Example

Below is a simple example.

/**
 * userController.js
 *
 * Purpose:
 *   - Handles HTTP requests related to user accounts.
 *     • GET /users/:id → fetch user by ID
 *     • POST /users    → create a new user
 *     • PUT /users/:id → update user information
 *     • DELETE /users/:id → delete a user
 *
 * Logic Overview:
 *   1. Validate request payloads (using Joi schema).
 *   2. Interact with UserService to perform CRUD operations on the database.
 *   3. Send appropriate HTTP status codes and JSON responses.
 *
 * Last Updated:
 *   2025-06-05  by Jane Doe (Refactored to use async/await and centralized error handler)
 */

import { validateUserPayload } from '../validators/userValidator';
import UserService from '../services/UserService';
import { handleError } from '../utils/errorHandler';

export async function getUser(req, res) {
  try {
    const { id } = req.params;
    const user = await UserService.findById(id);
    return res.status(200).json(user);
  } catch (err) {
    return handleError(err, res);
  }
}

// …rest of the CRUD handlers…

Having a comment block for each file is helpful because:

It explains what the file is for and how it generally works. The information is good for human and for AI.
By reading the comments, AI the overall design context, special logic or important points. AI can generate code more acuurately and prevent accidental errors or unintended consequences.
It provide valueable detail for bothcode review and security analysis in the future.

2. Make a Feature Documentation Library

Prompt:

Ensure features are documented in the ./docs directory.
- Before modifying code, review existing files in ./docs to understand current implementation.
- If no appropriate documentation exists, create a new Markdown file in ./docs outlining your analysis.
- After completing changes, update or add documentation in ./docs to match the new code.
- Finally, check the ./docs folder to see which files exist and decide if any need updating or deletion based on your changes.

Example

Imagine you’re adding a new “Bulk Email” feature to your CRM. Here’s how an AI generated document could look:

# Bulk Email Feature

## Purpose
Allow admins to send a templated email to multiple contacts at once.

## High-Level Flow
1. Admin uploads a CSV of email addresses  
2. System validates addresses via `validateCSV()`  
3. API enqueues emails in SendGrid batch queue  
4. Worker process sends out messages and logs results

## Data Model
- `EmailBatch` (id, templateId, status, createdAt)  
- `EmailRecipient` (batchId, email, status, errorMessage)

## API Endpoints
- `POST /api/bulk-email/start`  
  • Request Body: `{ templateId: string, csvFile: File }`  
  • Response: `{ batchId: string }`  
- `GET /api/bulk-email/status/:batchId`  
  • Response: `{ status: "pending" | "in_progress" | "completed", sentCount: number, failedCount: number }`

## Validation Rules
- CSV file max 10,000 rows  
- Template must exist and be enabled  
- Rate limit: 1 email batch per 5 minutes per org

Now, we have adocs foler that contains many such markdown files house deeper explanations — API design decisions, architecture diagrams, usage examples, and more.

Instead of scattering notes, diagrams, or instructions across private notes or comments, the dedicated ./docs is a sigle source of truth everyone knows exactly where to look.

3. Automate the Documentation

Writing the comment blocks and features documents once is great; keeping it current is game-changing.

You can put these two prompts into your AI code assistants’ system prompts, they will take effect each time you ask AI to make changes. It will keep the documents up to date all the time.

Each AI code assistant has its own way of customizing system prompts. In the case of Github Copilot, we can create and save the above in the file ‘./gihub/copilot-instructions.md, see Customize chat responses in VS Code

Conclusion

Documenting code isn’t something to be sacrificed anymore. Using the two prompts as system prompts, AI will create comprehensive documents to make your repository friendly and self-explanatory. — saving you time, reducing confusion, and even helping AI itself when working on it in the future.

Happy documenting!

Elevate Your AI-Driven Coding Workflow

yysun — Tue, 03 Jun 2025 16:30:56 +0000

Working with AI code assistants like GitHub Copilot, you need more than just simple, one-off, “write code” prompts. You can use some advanced techniques to create a structured, iterative process that ensures clarity, code quality, and alignment with your objectives.

1. Advanced AI-Driven Coding Techniques

Here are some techniques I usually found useful and correspondent prompts:

Request a plan, review and confirm: “provide your plan in a concise bullet list and wait for my confirmation before proceeding”
Request multiple options: “provide implementation options and comparisons and wait for me to confirm before proceeding”
Iterate step by step: “apply the changes step by step and wait for me to say "next" before proceeding to the next step”
Keep docs in sync: Eliminate outdated or missing documentation.

Using these prompts transforms the AI assistant into a structured collaborator that follows a reproducible workflow.

can be transformative—automating repetitive tasks, accelerating development, and offering creative suggestions.

2. Setting Up Prompt Alias

You have noticed though typing long instructions each time can become tedious. To solve the problem, we introduce prompt aliases—short, “magic words” that trigger the advanced behaviors described above:

AA: Request a concise plan before writing code.
CC: Compare implementation options.
SS: Apply changes incrementally, confirming at each step.
GG: Auto-generate or update documentation, including mermaid diagrams if needed.

All we need to do is create a system prompt for your AI coding assistant.

- I will use the following words to indicate how you should proceed with the code changes:
  - "AA": provide your plan in a concise bullet list and wait for my confirmation before proceeding.
  - "CC": provide implementation options and comparisons and wait for me to confirm before proceeding.
  - "SS": apply the changes step by step and wait for me to say "next" before proceeding to the next step.
  - "GG": summarize the features you implemented into a markdown file into the docs folder. 
      - If the file does not exist, create a new markdown file with existing features and the new changes.
      - If the file already exists, update the file by consolidating existing features with new changes.
      - Use mermaid diagrams if needed.

3. A Sample Interaction

Once customized the system prompt of AI code assistant, you can use the prompt alias like below:

Imagine you want to add a “purchase history” endpoint to your e-commerce API. Here’s how to orchestrate the AI assistant:

Plan Phase (AA):

You type: implement "purchase history" retrieval endpoint AA
- Then AI returns a plan:
  1. Create or modify the purchase_history database schema.
  2. Add a service layer function to fetch purchase records.
  3. Implement an Express route /purchase-history.
  4. Write unit tests for the new route and service.
  5. Update documentation in docs/FEATURES.md.
- You can review and confirm.
Compare Options (CC):

You type: design purchase history database. CC
- The AI lists:
  1. Relational join table (Pros: ACID compliance; Cons: join complexity)
  2. MongoDB collection (Pros: flexible schema; Cons: eventual consistency)
  3. Redis caching layer (Pros: fast lookup; Cons: non‑persistent)
- You reply: Let’s proceed with option 1 (relational join table).
Step‑by‑Step Implementation (SS):

You type: Start coding the purchase history feature. SS
- Step 1: The AI generates a database migration for a new purchase_history table (fields: id, user_id, product_id, quantity, timestamp).
- You review the SQL, run migrations locally, then say “next.”
- Step 2: The AI writes the service function getPurchaseHistory(userId) that queries the join table.
- You run a unit test, say “next.”
- Step 3: The AI implements the Express route /api/purchase-history/:userId.
- You verify functionality with Postman, then say “next.”
- Step 4: The AI generates unit tests for the route.
- You run tests, confirm all pass, then say “next.”
Documentation (GG):

You type: GG
- The AI checks for docs/FEATURES.md. If missing, it creates the file with a header “# Features,” adds a “## Purchase History” section, includes a description, endpoint details, sample request/response, and a mermaid sequence diagram.

Of course, these aliases can be used independently.

And you can change them to whatever magic word you like, as long as they are easy to type and easy to memorize!

4. Conclusion

Adopting advanced prompts elevates your AI-driven coding workflow from sporadic code suggestions to a structured, collaborative process. You gain:

Clarity and Focus: Eliminate scope creep with upfront planning.
Informed Decisions: Evaluate trade-offs before coding.
Quality Control: Vet every change to catch bugs early.
Up‑to‑Date Documentation: Automate or update docs to reduce technical debt.

By using prompt aliases saves your time of typing the prompts and makes you more productive.

Embracing these powerful prompt aliases now to focus on evaluating code quality also achieves unparalleled efficiency. Start today and experience the transformation.

Use AppRun with React

yysun — Sat, 29 May 2021 19:39:50 +0000

It only takes one line of code to use the elm-inspired AppRun architecture in React apps.

Introduction

React is a popular JavaScript library for building user interfaces.

AppRun is an elm-inspired event-driven library.

Using AppRun and React in conjunction is one of the best ways to build a web app. In this post, I will explain why and how-to.

If you are new to AppRun, please visit the AppRun Docs for more information.

An Example

Let's use the code from the React Hooks Doc as an example.

import React, { useState } from 'react';

function Example() {
  // Declare a new state variable, which we'll call "count"
  const [count, setCount] = useState(0);

  return (
    <div>
      <p>You clicked {count} times</p>
      <button onClick={() => setCount(count + 1)}>
        Click me
      </button>
    </div>
  );
}

The same app using the AppRun looks like below.

const state = 0;

const view = count => <>
  <p>You clicked {count} times</p>
  <button onclick={()=>app.run('add')}>
    Click me
  </button>
</>;

const update  = {
  add: state => state + 1
};

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

You can see the AppRun way is easier to understand. They are explained below.

AppRun Logic

Inspired by Elm, AppRun Application logic is broken down into three separated parts in the AppRun architecture.

State (a.k.a. Model) — the state of your application
View — a function to display the state
Update — a collection of event handlers to update the state

All applications and components have the same architecture. So when you want to understand any applications, you can always start with looking for where the state is, where the view is, and where the update is.

Use AppRun in React App

If you like the AppRun architecture, it is very easy to use AppRun in React apps. All you need to do is converting the AppRun component to a React component by calling the toReact function.

import React from 'react';
import { Component } from 'apprun/esm/component';
import toReact from 'apprun/react';

class MyComponent extends Component {
  state = 0;
  view = count => <div>
    <p>You clicked {count} times</p>
    <button onClick={()=>this.run('add')}>
      Click me
    </button>
  </div>;
  update  = {
    add: state => state + 1
  };
}

const App = toReact(MyComponent);
export default App;

Note: The React VDOM uses JSX. AppRun VDOM also uses JSX. They are similar. However, React VDOM does not have directives. So you cannot use the AppRun $onclick directive. Instead, you need to use the React onClick attribute.

Now, with just one line conversion to React component, we successfully used the AppRun component in a React app.

You can visit https://github.com/yysun-apprun to see an example React project created by the Create React App Cli that uses AppRun components.

Or you can visit the live Demo site: https://replit.com/@yysun/apprun-react

AppRun Benefits

Having the elm-inspired architecture in React apps, we have many benefits. I summarize them briefly here.

The state, view, and update are function have only dependencies to their input parameters. Without external dependency makes the three functions almost pure, which means it's easy to reason, easy to test, and easy to maintain.

For example, you can see that by making it event-driven, the update, a collection of the event handlers, can live outside the React component w/o the dependency to the setState function. Thus, you can use modules to organize them and test them easily.

We provide the state, view, and update to AppRun and wait for AppRun to call them following the Hollywood Principle (Don't call us. We call you). AppRun uses a state management system and event pub-sub system to combine the state, view, and update together.

For more information, please visit the AppRun Site, AppRun Docs Site,

Or read the AppRun Book from Apress

I hope you enjoy it.

This post updated from using three lines of code to just one line of code on May 30, 2021.

Make Code Run in Your Docs

yysun — Sun, 23 May 2021 16:06:25 +0000

Introduction

The recently updated AppRun Docs Site has made the code snippets in the documents runnable and editable, making the technical documentation interactive and much more fun to use.

The site is built with Material for MkDocs, a beautiful and powerful tool for building technical documentation site. We extended it by adding a web component built with AppRun to deliver the interactive experiences.

In this post, I Will explain how it's made. Let's start with reviewing the user experience.

User Experience

Technical documents usually have code snippets. Often the code has syntax highlighted for easy reading. However, users usually can only see screenshots but not live results of the code. Screenshots have limitations. For example, when describing how to make animation, a static screenshot is not helpful. We need a way to display the live code execution results.

See the Results

You can visit the AppRun Docs Page to see a live animation.

Try the Code

Furthermore, users might have been inspired by the code examples and want to try different ideas. Traditionally, they could copy and paste the code to run it in their code editors. It would be nice for users to edit the code right on the doc site and see the results.

You can click the "Try the Code" button of the AppRun Docs Page. It opens the AppRun Playground with an editor and preview pane to play the code.

The user experiences have much improved with the capabilities of seeing the code results and trying the code in technical documents.

Author Experience

Not only is it much more attractive to the readers, but also the authors will feel it much more enjoyable when writing the documents.

Present the Live Code

Traditionally, authors copy and paste the code snippets from their testing projects into the markdown documents as code blocks. The limitation is that they can only present the code but not the running code. Sometimes, it would be hard to describe the code behaviour. For example, describing a calculator could need a long text, but it could be easier to present the calculator for users to click.

You can visit the AppRun Docs Page to see a running calculator.

All we need to do is to add a web component, called apprun-play under the code blocks.

  ``js
  // code snippets
  ``
  <apprun-play></apprun-play>

Control the Presentation

You probably have noticed that the page shows only the results but not the source code. It is because we can control whether to show the source code. We can also decide whether to see the "Try the Code" button.

  ``js
  // code snippets
  ``
  <apprun-play hide_src="true" hide_button="true"></apprun-play>

You can visit the AppRun Docs Page to see an example of only displaying the running results.

We can present the code snippets, but we can also embed whole applications because the apprun-play web component supports HTML.

We can use the embedding external files feature of Material for MkDocs. This way, the markdown document does not include the source code and can remain simple and clean.

  <textarea>
  --8<-- "real-world.html"
  </textarea>
  <apprun-play style="height:350px" hide_src="true" hide_button="true"></apprun-play>

Automatic Test the Code

When it displays the code result automatically means that it is automatic testing of the code, which tells the author if the code works as expected.

Also, while writing, the authors can come up with new ideas. With apprun-play web component, they can edit the code and see the live results. Once it's done, they can copy and paste the code back into the document.

Overall, the apprun-play web component is a helpful tool for the document author.

How It's Made

Web components/custom elements are safe in the markdown documents. We can build web components out of the AppRun Components quickly.

The apprun-play web component is an AppRun component that gets the source code from its previous sibling element, a textarea, or a div with highlighted code. Then, the apprun-play web component creates an iframe for the code.

You can find the source code here and the compiled code here

Then, you can add it to the configuration file of Material for MkDocs, mkdocs.yml

extra_css:
  - assets/vendor/codemirror/codemirror.css

extra_javascript:
  - assets/vendor/codemirror/codemirror.js
  - assets/vendor/codemirror/mode/javascript/javascript.js
  - assets/vendor/codemirror/mode/xml/xml.js
  - assets/vendor/codemirror/mode/jsx/jsx.js
  - assets/apprun-play.js

That's it. The apprun-play web component is ready for use in all the markdown documents.

Finally, the AppRun Docs Site Github project is: https://github.com/apprunjs/apprun-docs/

Please enjoy and send pull requests.

Note: the cover image is a water colour painting I painted from the one by my favourite English painter, John Yardley.

A Dev Server Supports ESM

yysun — Sun, 13 Dec 2020 21:27:34 +0000

Introduction

Although we use the JavaScript modules (ESM) extensively while coding nowadays, we still cannot deploy the module-based code yet because the browsers don't know how to handle global modules. E.g., When developing applications using AppRun, we need a globe module of apprun.

import app from 'apprun'

The browsers don't know how to import apprun. Therefore, We still need to use JavaScript bundlers such as webpack, rollup, or parcel to bundle the modules.

But at least now, we can use the modules to speed up the development process. Recently, the Snowpack team introduced the concept of Unbundled Development, which is to leverage modules for speeding up the development process.

In the past, I was thinking to find or build a tool to convert the global modules to the modules links on unpkg after compilation.

The npm package CDN, unpkg.com supports delivering modules for along time. We can load apprun as a module from unpkg.

import app from 'https://unpkg.com/apprun?module'

Now, it seems that a development server is a different and better idea. So, I forked the live-server and made a development server for AppRun.

This post is to introduce the AppRun development server, called apprun-dev-server.

apprun-dev-server

This is a static web server for developing JavaScript/TypeScript using ES modules following the concept of Unbundled Development.

It serves the ES Modules from unpkg.com.
Based on live-server, so it reloads the page automatically
Also, it detects AppRun and can replace the module/Component while keeping the application state.

The best part of the apprun-dev-server is that it does NOT require any code in our components to handle the hot module replacement. It retains the component state; replaces the module; and then puts the state back. All done automatically.

If you want to refresh the state, you can reload the page in the browser by pressing F5 (on Windows) or Command+R (on Mac).

How to Use

You export Component as the default module export.

import { app, Component } from 'apprun';

export default class AboutComponent extends Component {
  state = 'About';
  view = state => <div>
    <h1>{state}</h1>
  </div>;
  update = {
    '#About': state => state,
  };
}

Then, you use the Component in the main file.

import About from './About';

new About().start('my-app');

Then, you use a module-type script tag in HTML.

<!DOCTYPE html>
<html lang="en">
<head>
  <meta charset="utf-8">
  <title>AppRun SPA</title>
</head>
<body>
  <script type="module" src="/dist/main.js"></script>
</body>
</html>

Turn on the compiler, TypeScript, or Babel in watch mode. And then, start the apprun-dev-server using npx.

npx apprun-dev-server

Apprun-dev-server monitors the file changes. If the changed JavaScript files (*.js) file have global modules. Apprun-dev-server replaces the global module's references to unpkg. In the server console, if you see the file names that have some dots '......' in front, they are the files modified.

Apprun-dev-server injects JavaScript code snippets in the index.html just like live-server. Also, Apprun-dev-server adds logic to detect AppRun and replace AppRun components.

You can download an example app to give it a try.

npx degit yysun/apprun-esm-server my-app

Configuration

Create a apprun-dev-server.config.js in your project:

module.exports = {
  port: 8181, // Set the server port. Defaults to 8080.
  host: "0.0.0.0", // Set the address to bind to. Defaults to 0.0.0.0 or process.env.IP.
  root: "public", // Set root directory that's being served. Defaults to cwd.
  open: false, // When false, it won't load your browser by default.
  ignore: '', // comma-separated string for paths to ignore
  file: "index.html", // When set, serve this file (server root relative) for every 404 (useful for single-page applications)
  wait: 1000, // Waits for all changes, before reloading. Defaults to 0 sec.
  mount: [], // Mount a directory to a route.
  logLevel: 2, //
}

Future Plan

Don't want apprun-dev-server to invoke compilers/loaders. It is perfectly fine to use the TypeScript compiler in watch mode. Apprun-dev-server is a webserver to serve modules. Nothing else.

Webpack is still needed and recommended for building production code for now.

The node-modules folder size is a problem. Apprun-dev-server can run from npx. It does not need to live in the node-modules. However, it does not get away from npm install and huge node-modules folder, because we still need referenced packages, ESLint, Jest... Good luck with future npm improvement.

Based on the opinions above, I will keep the apprun-dev-server simple. KISS!

Give it a try and send pull requests.

https://github.com/yysun/apprun-dev-server

ORM for .NET 5 Records

yysun — Sat, 21 Nov 2020 22:42:38 +0000

Object-Relational Mapping (ORM, O/R mapping tool) is a tool for converting data between object-oriented languages and relational databases. When programming using C#, an ORM tool helps to reduce the tedious field to field mapping work. The most famous one is the Entity Framework.

DragonCore ORM

Entity Framework and other ORM tools usually have a load of features, which makes them complicated and hard to control. I feel I need a very simple ORM tool that just can load data from the SQL server into C# objects and execute stored procedures. Therefore, I have created a simple ORM tool, call Dragon since .NET framework 1.1 and used it in many production projects. It has been updated to leverage new C# features along with the major C# version releases, such as generics, auto-properties, anonymous types, tuple destruction, and etc.

DragonCore is a port of Dragon to .NET 5 to support the latest and greatest C# 9 features, in particular the record types.

To use the DragonCore, install the NuGet package.

dotnet add package DragonCore

From Class To Record

The recent .NET 5 release announced C# 9 record type.

C# 9.0 introduces record types, which are a reference type that provides synthesized methods to provide value semantics for equality. Records are immutable by default.

Before the .NET 5 release, we use regular C# class.

public class User
{
  public int UserId { get; set; }
  public string Email { get; set; }
}

Now, we can use C# 9 record type.

public record User
{
  public int UserId { get; init; }
  public string Email { get; init; }
}

Although changing the keywords from class to record and from set to init does not look like big changes, we actually have implemented the concept of immutable reference types. No need to understand the in-depth theory, you only need to know the immutable reference types is better than regular class for loading data from the database and passing data to other layers of applications. Of course, you can review all the benefits from the record type document.

There is a short-hand syntax to create a record type, which is also known as a positional record. We can re-write the above User record as positional record.

public record User(int UserId, string Email);

The C# compiler creates the constructor, properties, and destructors out of the positional record. DragonCore supports the positional record syntax.

Strongly Typed Mapping

DragonCore can execute SQL queries and create C# strongly typed objects.

Database database = Database.Open(/*connection string*/);

public record User(int UserId, string Email);

var users = database.Query<User>(@"select UserId, Email from UserProfile");

The class/record property names don't need to match the table/view column names. The class/record property names match the field names in the SQL select statements. Therefore, we can use SQL select to define column alias to match the property names.

public record User(int Id, string Email);

var users = database.Query<User>(@"select UserId as Id, Email from UserProfile");

Also, we can have more class properties than the columns returned from the query. Extra columns are ignored, but the query will still return all the columns from the SQL server. Be aware to always be specific on the columns in production code and not to use "SELECT *".

The Query method also supports calling stored procedures for creating objects.

var (users, members, roles) = database.Query<TestUser, TestMemberShip, TestUserRole>("GetAllUserInfo");

There is also the QueryValue method that creates a SQL command and runs ExecuteScalar to return a single value from the SQL server.

Query Parameters

Query parameters are passed in as anonymous types.

var users = database.Query<User>(@"
    select UserId, Email from UserProfile 
    where UserId=@UserId", new { UserId = 2 });

This allows you to name parameters and pass data through the parameters easily.

Multiple Recordsets

The Query method supports up to 3 recordsets. The result objects are returned in a Tuple. We can use tuple destruction to unpack variables from the tuple.

var (users, members, roles) = database.Query<TestUser, TestMemberShip, TestUserRole>(@"
  select * from dbo.UserProfile
  Select * from dbo.webpages_Membership
  select * from dbo.webpages_Roles");

Execute Stored Procedure

The Execute method is for executing stored procedures. It creates a SQL command and runs ExecuteNonQuery.

Manage Transactions

Use the TransactionScope guaranteeing that database queries can commit or rollback as a single unit of work.

try
{
    Database database = Database.Open(/*connection string*/);
    using (TransactionScope scope = new TransactionScope())
    {
        database.execute(...);
        database.execute(...);
        database.execute(...);

        // The Complete method commits the transaction. If an exception has been thrown, the transaction is rolled back.
        scope.Complete();
    }
}
catch (TransactionAbortedException ex)
{
    writer.WriteLine("TransactionAbortedException Message: {0}", ex.Message);
}

Conclusion

I only want a simple tool to map SQL recordsets to C# objects. No repository pattern or unit of work pattern. I can handle transactions with stored procedures or TransactionScope. If you like me, give DragonCore ORM a try.

DragonCore ORM has only one class, called Database, which has four methods: Open, Execute, QueryValue, and Query.

Open: opens database connection using a connection string.
Execute: creates a command and runs ExecuteNonQuery.
QueryValue: creates a command and runs ExecuteScalar.
Query: creates a command with SQL statement(s) or stored procedure name and creates objects. The Query method supports up to 3 multiple recordsets.

Source Code

https://github.com/yysun/dragon-core

Pull Requests are welcome. Have fun coding.

Rust WebAssembly and AppRun

yysun — Mon, 30 Mar 2020 15:32:10 +0000

Introduction

WebAssembly has many different definitions on the Internet. I like the one from MDN the most, which says WebAssembly is a new binary assembly-like language that can run in the modern web browsers at near-native speed. There are many tools to compile code written in C/C++, Rust, Go, C#, etc. to be WebAssembly. It tells us that we can create high-performance code, but not using JavaScript/TypeScript

I decided to play with Rust. Rust is another hot buzzword. It is a relatively new programming language focused on performance and safety, especially safe concurrency. -- Wikipedia

This post describes how to create a WebAssembly package using Rust and use it in the AppRun applications from a JavaScript/TypeScript developer point of view. You will see the minimum steps of adding and using WebAssembly into your JavaScript/TypeScript project.

Setup

First, you will need the Rust toolchain, including rustup, rustc, and cargo for compiling Rust code, and wasm-pack for building, testing and publishing Rust-generated WebAssembly.

Install Rust

To install Rust on Mac/Linux, run the following command in the terminal.

curl --proto '=https' --tlsv1.2 -sSf https://sh.rustup.rs | sh

On Windows, I enabled the Windows Subsystem for Linux and used Rust in the Linux terminal.

Install wasm-pack

Once installed Rust, run the following command in the terminal.

cargo install wasm-pack

Believe it or not, that's all you need to create WebAssembly. Let's go back to the JavaScript/TypeScript world.

If you start from scratch, follow the next section to create an AppRun project.
If you already have an existing project, jump to the section of Create WebAssembly Project.

Create AppRun Project

Run the commands to create an AppRun project:

mkdir your-app-name
cd your-app-name
npx apprun -i

Wait a few minutes for installing the npm packages, and then run the npm command:

npm start

You will see a hello world application running.

AppRun Hello World

Next, we will add WebAssembly to this project.

Create WebAssembly Project

Let's create a Rust project by running the following command:

cargo new wasm --lib

The command creates a folder called wasm and two files under the folder your-app-name/wasm: Cargo.toml and src/lib.rs.

It is a regular Rust project, not a WebAssembly yet. You will need to add wasm-bindgen as the dependency to make it target WebAssembly. Open Cargo.toml and add the following sections.

[lib]
crate-type = ["cdylib"]

[dependencies]
wasm-bindgen = "0.2.60"
js-sys = "0.3.37"

wasm-bindgen is a Rust library that facilitates high-level interactions between wasm modules and JavaScript. js-sys is the waw bindings to JS global APIs for projects using wasm-bindgen.

Now, you can use wasm-pack to build a WebAssembly.

cd wasm
wasm-pack build

Use WebPack

Since the AppRun project is a WebPack project, we can use the wasm-pack-plugin to unify the build process that creates the WebAssembly and JavaScript code at the same time. Go ahead to add the package:

npm i @wasm-tool/wasm-pack-plugin -D

And add the wasm-pack-plugin into the webpack.config.js.

const WasmPackPlugin = require("@wasm-tool/wasm-pack-plugin");
module.exports = {
  ...
  plugins: [
    new WasmPackPlugin({
      crateDirectory: path.resolve(__dirname, ".")
    }),
  ]
  ...
}

Also, because of the wasm-pack-plugin generates the dynamic import module, you need to modify tsconfig.json file to set the module to be esnext.

{
  "compilerOptions": {
    ...
    "module": "esnext",
    ...
  }
}

Finally, the npm scripts: npm start and npm run build will build the TypeScript code as well the Rust code.

Let's write some Rust code.

WebAssembly and AppRun

We will demonstrate two interactions between the WebAssembly and the AppRun application.

Call the WebAssembly from the AppRun application
Call the AppRun application from the WebAssembly

Call WebAssembly

First, we create a Rust function in the wasm/src/lib.rs file.

use wasm_bindgen::prelude::*;

#[wasm_bindgen]
pub fn add(a: i32, b: i32) -> i32 {
  a + b
}

This function adds two numbers. We can make a counter application from it. Here is the counter application in AppRun.

import app from 'apprun';

let wasm;
import('../wasm/pkg').then(module => wasm = module);

const state = {
  title: 'Hello world - AppRun !',
  count: 0
}

const add = (state, num) => ({
  ...state,
  count: wasm.add(state.count, num)
});

const view = ({ title, count }) => <>
  <h1>{title}</h1>
  <h1>{count}</h1>
  <button $onclick={[add, -1]}>-1</button>
  <button $onclick={[add, +1]}>+1</button>
</>;

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

You can see from the code above:

Wasm-pack has created a JavaScript module that we can import dynamically.
We can call the WebAssembly function just like a regular JavaScript function from a module.

Running the application, we have a counter that uses the WebAssembly function.

Counter with WASM

Next, let's see how does the WebAssembly function call AppRun functions.

Call the AppRun

Open wasm/src/lib.rs file and add the following functions.

#[wasm_bindgen]
extern "C" {
  #[wasm_bindgen(js_namespace = app)]
  fn run(event: &str, p: &str);
}

#[wasm_bindgen(start)]
pub fn start() {
  run("@hello", "hello world from rust");
}

The first function named run binds to the AppRun app.run function.
The second function named start runs automatically when the WebAssembly is loaded.
The start function calls the run function to send a '@hello' event to AppRun.

Back to AppRun code, we will handle the '@hello' event.

import app from 'apprun';

let wasm;
import('../wasm/pkg').then(module => wasm = module);

const state = {...}

const add = (state, num) => ({...});

const view = ({ title, count }) => <>...</>;

const update = {
  '@hello': (state, title) => ({...state, title})
}

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

Now, when the application starts, it displays the messages sent from the WebAssembly.

Message from wasm

We have successfully made the two-way interactions between the WebAssembly and the AppRun application.

Souce Code

You can run the live demo: https://yysun.github.io/apprun-rust.

Or visit the source.

yysun / apprun-rust

AppRun Rust Demo App

AppRun Rust Demo

This is an AppRun app template for developing WebAssembly using Rust.

You need the Rust tool chain, and wasm-pack installed first.

Use npm start to start the dev server
Use npm run build to build for production

Have fun.

View on GitHub

You also can use this project as an AppRun application template. Run the command to create your application.

npx degit yysun/apprun-rust my-app

Conclusion

This post should give you a quick start to use Rust/WebAssembly in the AppRun applications. The demo project shows the two technologies interact with each other very well. You can use the demo project as a template.

We have now opened the door to a new world. There are much more potentials to explorer.

Serverless App Using Firebase and AppRun

yysun — Thu, 26 Mar 2020 18:29:54 +0000

Introduction

I have been writing about the application architecture without REST, which includes the underlying architecture using WebSockets and the database-driven architecture. In this post, I will continue the journey to make a serverless application architecture using Firebase and AppRun.

You will see how easy it is to use AppRun's event system with the Firebase stack to develop applications that have the full business logic process capabilities, such as authentication, authorization, request logging, and real-time database, and without REST layer.

Finally, we can make the application a serverless deployment to Firebase.

The Architecture

The example application uses the following technologies:

Firebase Cloud Firestore as the backend database
Firebase Cloud Functions for business logic process
Firebase Hosting to host the frontend
Firebase Authentication

Firebase is Google's mobile platform that helps you quickly develop high-quality apps and grow your business.

I will focus on the architecture instead of step by step instructions. If you are not familiar with the Firebase suite of products, please visit the docs and search for the tutorials.

The architecture can be summarized in the diagram below.

Figure 1. Architecture Diagram

Let's get into the details.

Event Pub-Sub Using FireStore

The center of the architecture is the Firebase Cloud Firestore. Firestore is a real-time database that keeps your data in-sync across client apps. When one client saves the data, FireStore pushes the data to all other clients.

In the AppRun applications, we use app.on to publish events. If we save the events to FireStore, the events can be handled by other applications. It is the step (1) shown in Figure 1 above.

Firestore also triggers Cloud Functions.

Business Logic Process Using Cloud Functions

Cloud Functions is Google Cloud's serverless compute platform. It runs on the server, not in the client apps. Therefore it is the best technology for business logic processing, authentication, and authorization. Functions are serverless. Functions run on Google's server, so we don't need to provision, manage, or upgrade the server.

The Functions are event-driven (the magic word, I love). Firestore can trigger Functions upon data updates. When we save the events into FireStore, FireStore triggers the Function to handle the events automatically. It is the step (2) in Figure 1.

Real-Time Data Sync Using FireStore.

During the Functions event handling, it writes the updated data back to FireStore (step (3) in Figure 1). FireStore pushes the update to the frontend applications (step (4) in Figure 1). The frontend application listens to FireStore changes and publishes AppRun events for the frontend logic process to run.

Now, the event handling cycle is completed. Let's see it in action with an example.

Example

The example is a ToDo application.

Figure 2. ToDo Application

Save Events to FireStore

As usual, in the AppRun applications, we convert the DOM events into AppRun events. E.g., When users click the add button, we publish the //: event.

// in JSX
<button $onclick={[add]}>Add</button>

const add = () => {
  app.run('//:', '@create-todo', {
    title: (document.getElementById('new_todo').value,
    done: 0
  })
}

The //: event handler saves the event into FireStore.

const db = firebase.firestore();
app.on('//:', (event, data = {}) => {
  db.collection(`events`).add({ uid, event, data })
});

There is a top-level collection, called events in FireStore. We save the user id (obtained using Firebase anonymous authentication), event name (@create-todo), and event parameters (the new to-do item).

FireStore triggers our Function, which is monitoring the events collection.

Handle Events in Functions

exports.updateTodo = functions.firestore.document('events/{Id}')
  .onWrite((change, context) => {
    const dat = change.after.data() as any;
    const { uid, event, data } = dat;
    const db = admin.firestore();
    const todos = db.collection('/users/' + uid + '/todos');
    switch (event) {
      case '@create-todo': return todos.add(data);
      case '@update-todo': ...
      case '@delete-todo': ...
      case '@delete-all-todo': ...
      default: return;
    }
});

The Function destructs the user id, event name, and event parameters and handles it accordingly, e.g., it adds a new Todo item data into FireStore upon the '@create-todo' event. And so on so forth.

FireStore then pushes the data change to the frontend.

Real-Time Data in Frontend

In the frontend, we subscribe to the onSnapshot of FireStore and publish the AppRun event, '@show-all'.

const db = firebase.firestore();
db.collection(`users/${uid}/todos`).onSnapshot(snapshot => {
  app.run('@show-all', 
    snapshot.docs.map(d => ({ id: d.id, ...d.data() })))
});

Now, we are back to our AppRun application world, in which you can see the three familiar parts: state, view, and update.

import app, { Component } from 'apprun';

const state = {
  filter: 0,
  todos: []
}

const add = () => {
  app.run('//:', '@create-todo', {
    title: (document.getElementById('new_todo').value,
    done: 0
  })
};
const toggle = (_, todo) => { app.run('//:', '@update-todo', { ...todo, done: !todo.done }) };
const remove = (_, todo) => { app.run('//:', '@delete-todo', todo) };
const clear = () => { app.run('//:', '@delete-all-todo') };

const view = ({todos}) => {...}

const update = {
  '@show-all': (state, todos) => ({ ...state, todos })
}

The Firebase ToDo application shares the same architecture as in the Database-Driven Application Post. They are only different in events. The Firebase ToDo application saves the events to FireStore. The Database-Driven Application sends and receives the events through the WebSockets.

If you are new to AppRun, read the AppRun Book or visit AppRun Docs.

Live Demo and Source Code

You can play with the live demo at https://apprun-demo.firebaseapp.com.

Or visit the project on Github.

yysun / apprun-firebase

A serverless application using Firebase and AppRun

AppRun Firebase Serverless App

Use npm start to start the dev server
Use npm test to run unit tests
Use npm run build to build for production

This is an application built with AppRun.

View on GitHub

Conclusion

The AppRun event pub-sub pattern looks so simple (just app.run and app.on), yet so powerful. It is not only useful inside the frontend app. It shines more in crossing process boundaries, such as in the cases of WebSockets, Web Workers, Electron Apps, Firebase of course, and more ...

Learn more about AppRun and build event-driven applications.

Avoid Spaghetti Code using AppRun

yysun — Tue, 24 Mar 2020 00:57:06 +0000

Introduction

Recently I was asked to refresh an old application that has the so-called spaghetti code. There are different levels of problems. Many can be solved just refactoring to use new JavaScript language features such as using modules. However, two problems are hard to solve without the help of a framework, which I call them:

Direct State Update
Rendering Fragments

In the post, I will show you how AppRun can help to solve the problems. Therefore we can avoid spaghetti code.

Example

I cannot show the real production code I am dealing with, so I made an abstracted example to demonstrate the problems. As usual, I am using a counter example that has two buttons. One to increase the counter. The other one to decrease the counter. Also, I made it a litter complicated to show how many times each button is clicked.

Problem Code

The code below uses jQuery. jQuery is a library that provides the convenience to access and manipulation of the DOM. It does not provide any architectural guidance. jQuery code is similar to the vanilla JavaScript code that can go wild.

$(function () {  

    // global state
    let count = 0
    let count_plus = 0
    let count_minus = 0

    function plus() {
      // state update
      count ++
      count_plus ++

      // rendering
      $('#total').html(count)
      $('#plus').html(`+ (${count_plus})`)
    }

    function minus() {
      // state update
      count --
      count_minus ++

      // rendering
      $('#total').html(count)
      $('#minus').html(`- (${count_minus})`)
    }

    $('#plus').on('click', plus)
    $('#minus').on('click', minus)

  })

You can see from the above code that event handlers plus and minus have the problem patterns. They update the state directly. They also render the DOM in different pieces.

But the real problem is that there isn't a way to break them further. The state has to be shared globally. And the rendering has to be different in each click event.

In much more complicated real applications, the logic could be long and tangled even more.

AppRun

AppRun is the framework that can solve the two problems.

If you are new to AppRun, read the AppRun Book or visit AppRun Docs.

State Management

AppRun is a state management system. It is also an event-driven system that has an event lifecycle. During an AppRun event lifecycle:

AppRun let you update the state when needed
AppRun let you create a virtual DOM out of the state when needed
AppRun renders the virtual DOM when needed.

Sort of following the Hollywood Principle (Don't call us. We call you.) here, we provide code pieces to AppRun and wait for AppRun to call them.

We write functions to update the state. AppRun gives the current state. We create a new state based on the current state.

const minus = (state) => ({ ...state,
  count: state.count - 1,
  count_minus: state.count_minus + 1
});

const plus = (state) => ({ ...state,
  count: state.count + 1,
  count_plus: state.count_plus + 1
});

We will be able to concentrate on the parts that are needed to update. We can spread out the rest of the state using the spread operator. Also, because there is no reference to a shared global object, it is very easy to unit test the state update logic.

DOM Rendering

We also write a view function that AppRun will call with the state as the input parameter. We usually use JSX in the view function to create a virtual DOM, which is just data structure. The view function does not render the DOM. AppRun renders the DOM using a diffing algorithm. It only renders the DOM that is needed to change. Therefore, we only need one view function for all events. AppRun takes care of the differential rendering accordingly.

const view = ({ count, count_plus, count_minus }) => html`
  <h1>${count}</h1>
  <button onclick="app.run('minus')">- (${count_minus})</button>
  <button onclick="app.run('plus')">+ (${count_plus})</button>`

The view function always returns the same result as long as the state is the same. It also does not change the state or anything outside the function, which means it has no side effects. We can make the view function a pure function. There are many benefits of using pure function, including but not limited to the unit testing. It makes the UI code easy to unit test.

Using AppRun, we have a counter application made from the state, _view, and update as shown below.

// initial state object
const state = {
  count: 0,
  count_plus: 0,
  count_minus: 0
}

// one view function to render the state, its' a pure function
const view = ({ count, count_plus, count_minus }) => html`
  <h1>${count}</h1>
  <button onclick="app.run('minus')">- (${count_minus})</button>
  <button onclick="app.run('plus')">+ (${count_plus})</button>
`

// collection of state updates, state is immutable
const plus = (state) => ({ ...state,
  count: state.count - 1,
  count_minus: state.count_minus + 1
});

const minus = (state) => ({ ...state,
  count: state.count + 1,
  count_plus: state.count_plus + 1
});

app.start(document.body, state, view, {plus, minus});

With the AppRun state management and DOM differential rendering in place, we no longer have the problem mixing state update with DOM rendering.

Usually, at this moment, I will show you the live demo on glitch. This time, I will show the interactive notebook I made on observable HQ. I feel I like the notebook more and more.

https://observablehq.com/@yysun/apprun-helps-to-avoid-spaghetti-code

Conclusion

No matter how complex the application is, we will always have three parts, the state, view, and update. We no longer mix the state update with DOM rendering. Because the three parts are totally decoupled, our codebase is so much easier to understand, test, and maintain.

Create a Phoenix LiveView Like App in JS with AppRun

yysun — Sat, 21 Mar 2020 16:23:23 +0000

Introduction

When I was creating the AppRun Websockets Template, I thought I was the only crazy person to push and run the 1 + 1 calculation on the server-side until I saw this video.

Phoenix LiveViewis a server-side solution using the Elixir programming language.

My AppRun WebSockets solution shares the same idea with Phoenix LiveView.

However, the AppRun solution is 100% JavaScript. For those JavaScript/TypeScript developers that are not ready to learn another programming language, the AppRun solution is for you.

This post is a step by step instruction of how to create a WebSockets based AppRun application.

Create the Project

To get started, run the following commands in the terminal or command shell.

npx degit apprunjs/apprun-websockets my-app
cd my-app
npm install
npm start

You will see a single page application using Bootstrap.

Project Structure

The project has a typical express JS project structure.

Figure 1. Project Structure

server directory has the server-side code
server/index.js is the webserver
src directory has the client-side code
public directory has the static assets
public/index.html is the default web page of the app

The project also has a few npm scripts.

npm start:client: compiles and watches the client-side app
npm start:server: starts the webserver
npm start: starts client and server
npm run build: build the client-side app for production

Understand the Architecture

Client Side

On the Home page of the SPA, there are two counters. One runs locally in the browser. One runs on the server.

import { app, Component } from 'apprun';

export default class HomeComponent extends Component {
  state = 0;
  view = state => {
    const add = (state, num) => state + num;
    return <div>
      <h1>{state}</h1>
      <div>
        <button $onclick={[add, -1]}>-1</button>
        <button $onclick={[add, +1]}>+1</button>
        <div>Run the counter locally</div>
      </div>
      <hr />
      <div>
        <button $onclick={['//ws:', '@add', state, -1]}>-1</button>
        <button $onclick={['//ws:', '@add', state, +1]}>+1</button>
        <div>Run the counter on server through web sockets</div>
      </div>
    </div>
  };
  update = {
    '@add': (_, state) => state
  }
}

They all use the AppRun event-driven programming model to trigger the state update and render lifecycle. The local counter uses local event directive. The server counter uses a global event //ws:, which means the send it to sever. The event parameters are @add, 1 or @add -1.

The main.tsx has five lines of code to send the event to the server through the web socket. The event name is @add. The event parameter is 1 or -1.

const ws = new WebSocket(`ws://${location.host}`);
app.on('//ws:', (event, state, ...args) => {
  const msg = { event, state, args };
  ws.send(JSON.stringify(msg));
});

Server Side

On the server-side, index.js creates an express server and listen to the web socket communication. When it receives messages, it publishes the messages using AppRun.

const apprun = require('apprun').app;
require('./add');
const express = require('express');
const { createServer } = require('http');
const app = express();
const server = createServer(app);
const wss = new WebSocket.Server({ server });
wss.on('connection', function(ws) {
  ws.on('message', function (data) {
    try {
      const json = JSON.parse(data);
      apprun.run(json.event, json);
      ws.send(JSON.stringify(json));
    } catch (e) {
      console.error(e);
    }
  });
});

Yes. AppRun runs on the server too to provide server-side event-driven programming.

The add.js is a server-side module that handles the @add event. It does the calculation to update the state. Then, in index.js, it sends results back to the web socket as an event using the same event name @add.

const app = require('apprun').app;
app.on('@add', function (data) {
  data.state += data.args[0];
});

Back to Client

The main.tsx receives the event from the web socket. It just needs to publish as it is. The event is a global event that has the name @add. The home page then handles the @add event to get the state calculated on the server.

ws.onmessage = function (msg) {
  const {event, state} = JSON.parse(msg.data);
  app.run(event, state);
}

We can summarize the process in the diagram below.

Figure 2. Events Between Client and Server

Next Steps

You can use the AppRun—WebSockets template as the start point. The template has all you need to create your Phoenix LiveView like applications.

Or you can copy about 20 lines of JS code from the main.tsx and index.js into your existing application to start leveraging the power of WebSockets. E.g., database-driven applications using WebSockets.

Live Demo

Conclusion

Because we use JavaScript, our applications are full-featured SPA. We can have Bootstrap, D3, ChartJS and, even JQuery plug-ins.

The AppRun WebSockets solution is so simple that it does not even worth being an npm package. Use the AppRun—WebSockets template or copy about 20 lines of code into your codebase, you will have Phoenix LiveView like applications.

One last thing to mention is that Phoenix LiveView does the server-side rendering (SSR), which is also trivial using AppRun. However, I favor the Progress Web App (PWA) over SSR because PWA provides offline, home screen icon, and many other features. There is also an AppRun template for PWA.