@axiosleo/koapp

@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

• If @axiosleo/koapp is installed in the current project, skills are copied from node_modules/@axiosleo/koapp/assets/skills/.
• If the project does not depend on @axiosleo/koapp, the CLI prompts to install it first.
• 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.