@axiosleo/koapp

A framework designed for rapid web application development with Node.js

Built on Koa

npm install @axiosleo/koapp

Initialization

npx @axiosleo/koapp init <app-name> -d <optional-dir>

# Show help information
# npx @axiosleo/koapp init -h

Quick Start

const { KoaApplication, Router, success } = require("@axiosleo/koapp");

const handle = async (ctx) => {
  success({
    message: "Hello World!",
  });
};

const router = new Router("/test", {
  method: "any",
  handlers: [handle],
});

const app = new KoaApplication({
  port: 8088,
  listen_host: "localhost", // Use 0.0.0.0 for public access
  routers: [router],
});
app.start();

// Open http://localhost:8088/test

AI Skills

@axiosleo/koapp ships a bundle of AI Agent Skills so tools like Cursor and Claude Code can generate framework-correct code for you. Each skill is a self-contained SKILL.md with YAML frontmatter, bundled under node_modules/@axiosleo/koapp/assets/skills/ after installation.

Install into a project

# After: npm install @axiosleo/koapp
npx @axiosleo/koapp skills --install=cursor
npx @axiosleo/koapp skills --install=claude

This copies the skills into ./.cursor/skills/ or ./.claude/skills/ in the current project, making them visible to the matching AI tool.

Install for the current user

npx @axiosleo/koapp skills --install=cursor --scope=user
npx @axiosleo/koapp skills --install=claude --scope=user

Writes to ~/.cursor/skills/ or ~/.claude/skills/, shared across every project on this machine.

Options

| Flag | Values | Default | Description | | --- | --- | --- | --- | | --install, -i | cursor, claude | required | Which tool's skills directory to target | | --scope, -s | project, user | project | Where to write the skills | | --force, -f | boolean | false | Overwrite existing skill directories without prompting |

Bundled skills

| Skill | Purpose | | --- | --- | | koapp | Framework overview + navigation to other skills | | koapp-apps | Choose and configure KoaApplication (HTTP), SocketApplication (TCP), or WebSocketApplication | | koapp-router | Define routes, path params, validators, nested routers | | koapp-response | Send responses via success / failed / result / response / error | | koapp-controller | Organize handlers into classes by extending Controller | | koapp-model | Validate and serialize structured data with Model | | koapp-sse | Stream Server-Sent Events with KoaSSEMiddleware |

How the installer picks the source

1. If @axiosleo/koapp is installed in the current project, skills are copied from node_modules/@axiosleo/koapp/assets/skills/.
2. If the project does not depend on @axiosleo/koapp, the CLI prompts to install it first.
3. If the local install is an older version without the skills assets, the CLI falls back to the skills shipped inside the npx-executed copy and reminds you to run npm install @axiosleo/koapp@latest.

Uninstall

rm -rf ./.cursor/skills/koapp*    # or ./.claude/skills/koapp*
# user scope
rm -rf ~/.cursor/skills/koapp*    # or ~/.claude/skills/koapp*

More Examples

• Request Validation

See validatorjs for more rule examples

See Router examples for more usage: tests/bootstrap.js

const { Router } = require("@axiosleo/koapp");

const router = new Router("/test", {
  method: "any",
  validator: {
    // URL params, like `/test/{:id}`, where 'id' is required and must be an integer
    params: {
      id: "required|integer",
    },
    query: {
      name: "required|string",
    },
    body: {
      age: "required|integer",
    },
  },
  handlers: [],
});

• File Operations

// npm install @koa/multer
// npm install -D @types/koa__multer

const multer = require("@koa/multer");

root.post("/upload", async (context) => {
  // Array of files
  const upload = multer();
  const func = upload.any();
  await func(context.koa, async () => {});
  const file = context.koa.request.files[0];
  context.koa.set("content-type", file.mimetype);
  context.koa.body = file.buffer;
  context.koa.attachment(file.originalname);
});

• Server-Sent Events (SSE)

const { _foreach, _sleep } = require("@axiosleo/cli-tool/src/helper/cmd");

const test = async (context) => {
  await _foreach(["0", "1", "2", "3"], async (item, index) => {
    context.koa.sse.send({ data: { item, index } });
    await _sleep(1000);
  });
  context.koa.sse.end();
};

const { KoaSSEMiddleware } = require("@axiosleo/koapp");

root.any("/sse", async (context) => {
  const func = KoaSSEMiddleware();
  await func(context.koa, async () => {});
  context.koa.sse.send({ data: "hello, world!" });
  process.nextTick(test, context);
});

License

This project is open-sourced software licensed under MIT.