zeffon / koa-web

The scaffolding of building Node Service with Koa2 + TypeScript.

Language : English | 简体中文

Koa Web

The scaffolding of building Node Service with Koa2 + TypeScript.

Features

The presets template are:

Template	Feature
Mini	Exception, Validator, API Doc
Lite	Mini + Database
Standard	Lite + Auth, Log
Full	Standard + Redis, Cache, Test-Unit
Generator	generate app module code and database table

• 💡 TypeScript: support TypeScript
• 🚀 Exception：Global exception handling
• ✈️ Validator：Practical and efficient data validation usage
• 📝 API Doc：API Doc UI
• 🍀 Database：Support for Sequelize connections
• ✍️ Auth：General JWT authorization
• 📖 Log：Log SQL and error logs
• 🔥 Redis：Support for Redis database connections
• ⚡ Cache：Support for Local Cache
• ✅ Test-Unit：Support unit test

Usage

The koa-web supports quick creation of project through the create command.

Scaffolding Your First koa-web Project

With NPM:

$ npm create koa-web@latest

With Yarn:

$ yarn create koa-web

With PNPM:

$ pnpm create koa-web

Here are the default main npm scripts in a scaffolded koa-web-starter project:

{
  "scripts": {
    "dev": "nodemon", // start dev serve
    "build": "tsc && tsc-alias", // build project
    "serve": "node dist/app.js" // start build serve
  }
}

cd koa-web-starter

npm install

npm run dev

# please open in: http://127.0.0.1:3100/api/doc.html

Project Layout

This is template-koa-standard layout

├── src
│   ├── app.ts              // koa start
│   ├── app                 // app modules
│       ├── api             // controller layer
│       ├── dto             // Data Transfer Object
│       ├── model           // sequelize model
│       ├── service         // service processing layer
│       └── share           // common util directory
│   ├── config              // env config
│   ├── typings             // ts type
│   └── core                // core mudules
│       ├── init.ts         // core start
│       ├── global.ts       // global var
│       ├── tool.ts         // tool
│       ├── exception       // global exception
│       ├── swagger         // api docs and validator
│       ├── database        // database modules
│       ├── auth            // auth modules
│       └── log             // log modules
├── .gitignore
├── nodemon.json            // nodemon watch files to run serve
├── package.json
├── README.md
└── tsconfig.json

Generator

koa-web-generator can quickly generate koa-web's app module code and database table.

Generate content: model, service, API, and DTO files.

Automatically generate database tables is turned off by default.

1. pull project & install deps

   pnpm create koa-web koa-web-generator --template generator
   
   cd ./koa-web-generator
   
   pnpm install

2. Add the models you want to generate in ./src/index.ts

   Every model is already contains id, created_at, updated_at, deleted_at.

   const models: ModelProps[] = [
     {
       name: 'user_alpha',
       comment: 'user comment',
       fields: [
         {
           fieldName: 'username',
           type: 'STRING(20)',
           allowNull: false,
           unique: 'username_idx',
         },
         {
           fieldName: 'password',
           type: 'STRING',
           allowNull: false,
           comment: 'password comment',
         },
         {
           fieldName: 'type',
           type: 'BOOLEAN',
           defaultValue: '0',
         },
       ],
     },
   ]

3. start generate

   pnpm start

After generation is complete, you can get such as files in ./src(model | service | api | dto) You can copy these files into your koa-web project.

Don't forget, the file ./src/model/index/ts also has generated content.

License

MIT

Copyright (c) 2022-present, Zeffon Wu