@axiosleo/koapp

> Built on Koa

npm install @axiosleo/koapp

Initialization

koapp init asks which project to generate. Pressing enter selects the simple TypeScript service. Pass -t to skip the prompt.

| Template | Flag | What you get | | --- | --- | --- | | Simple TypeScript app (default) | -t simple-ts | One koapp HTTP service and sample routes. No database. | | Simple JavaScript app | -t simple-js | The same service in CommonJS, with no compile step. | | Full monorepo | -t monorepo | pnpm workspace: admin Session API, Api-Keys, and SQLite. |

npx @axiosleo/koapp init <app-name> [-d <dir>] [-t simple-ts|simple-js|monorepo]
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

1. If the project does not depend on @axiosleo/koapp, the CLI prompts to

1. If the local install is an older version without the skills assets, the

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.