Welcome to generator-koa2-api-generator 👋

Yeoman generator to create a base structure for APIs based in koa2 framework, using tools such as: eslint, prettier, swagger and others

What's changed? See generator-koa2-api-generator releases

🏠 Homepage

This generator was created using generator-esmodules-generator version 1.0.1

Includes configuration for development environment

Example of a generator created by generator-koa2-api-generator:

Index

• Installation
• Prerequisites
• Arguments and options
• Project structure
• Generators included
• The question: Do you want to automatically run the scripts that configure the package, then installing the dependencies?
• The scripts in package.json
• Getting To Know Yeoman
• Author
• Contributing
• Show your support
• License

Installation

First, install Yeoman and generator-koa2-api-generator using npm (we assume you have pre-installed node.js).

npm install -g yo
npm install -g generator-koa2-api-generator

Then generate your new project:

yo koa2-api-generator project_name

Prerequisites

First, you must create a folder, then you enter it using the terminal. Finally you runs.

yo koa2-api-generator project_name

Example:

PS C:\Users\...\new_koa2_api_project> yo koa2-api-generator project_name

Arguments and options

The generator-koa2-api-generator include two arguments called projectName and databaseDriver (postgresql or mysql, or mariadb). projectName is a required argument:

For example: If you want to create a new koa2 api called koa2_api_project (projectName = koa2_api_project) with postgresql plugin, you should use:

yo koa2-api-generator koa2_api_project postgresql

The generator-koa2-api-generator include various options, these are:

option	value	default	description	example
runGitInit	Boolean	false	Run git init automatically, then installing the dependencies	yo koa2-api-generator project_name --runGitInit
runPackageScripts	Boolean	false	Run the scripts that configure the package, then installing the dependencies	yo koa2-api-generator project_name --runPackageScripts
useDocker	Boolean	false	Add docker support using DockerFile, .dockerignore and others	yo koa2-api-generator project_name --useDocker
nodeVersion	Number	16	Node version used in DockerFile. (FROM nodeVersion). Recommended to use node 16, 18, 20 or 21	yo koa2-api-generator project_name --nodeVersion=21
projectFolderName	String	api	Project folder name used in DockerFile. (WORKDIR /usr/src/projectFolderName)	yo koa2-api-generator project_name --projectFolderName=project_folder_name
useDockerCompose	String	false	Add Docker Compose support.	yo koa2-api-generator project_name --useDockerCompose
databaseName	String	null	Select the database to which the application will connect. Accepts the values: postgresql, mysql and mariadb.	yo koa2-api-generator project_name --databaseName=postgresql

Project structure

The project generated by generator-koa2-api-generator includes:

Default project structure

• api (folder): In this folder there are project configurations and the src folder that contains the source code

  • .husky (folder): Contains git hook used by husky
  • .env (file): Contains the API environment variables.
  • .env.example (file): Contains an example of API environment variables used to create a .env file.
  • .eslintignore (file): Files and folders ignored by eslint.
  • .eslintrc.yml (file): Configuration used by eslint.
  • .gitignore (file): Files ignored by git.
  • .lintstagedrc.json (file): Configuration used by lintstaged.
  • .prettierignore (file): Files and folders ignored by prettier.
  • .prettierrc.json (file): Configuration used by prettier.
  • .sequelizerc (file): Configuration used by sequelize-cli.
  • api-specification (file): Contains specification used by openapi-comment-parser.
  • babel.config.json (file): Configuration used by babel. In this case babel-register (.sequelizerc).
  • commitlint.config.js (file): Congiguration used by commitlint.
  • package.json (file): Contains dependencies, dev dependencies, scripts, etc.
  • README.md (file): Documentation generated by generator-koa2-api-generator.
  • src (folder): Contains the source code:
    • config (folder): Contains configuration files, for example database.js (contains environment varibles used by sequelize), jwt.js (contains environment variables used by jsonwebtoken) and openapi.js (contains the configuration used by openapi-comment-parser).
    • db (folder): Contains folders used by sequelize.
      • migrations (folder): This folder contains CommonJS Modules (files with extension .cjs and use require/module.exports). Includes a default user migration.
      • models (folder): This folder contains ES Modules (by default the project generated by generator-koa2-api-generator uses ES Modules, files with extension .js and use import/export). Includes a default user model. The index.js file loads the models exporting the orm constant.
      • seeders (folder): This folder contains CommonJS Modules (files with extension .cjs and use require/module.exports).
    • routes (folder): Contains the koa routers used by the project.
      • authentication (folder): Contains functions and routers to authenticate the users with json web token.
      • swagger (folder): Contains functions and routes to create documentation using swagger.
      • user (folder): Contains functions and routes to register, obtain and modify an user. Uses default model user
      • index.js (file): Contains the main koa2 router with prefix 'api/v1' and mounts the others routers.
    • schemas (folder): Contains openapi schemas and json schemas.
      • json (folder): Contains json schemas.
        • index.js: Loads the json schemas using ajv, ajv-errors and ajv-formats. Exports the jsonSchema constant and the simpleJsonSchemaValidation function, the json schemas file should have the file name : 'name_of_json_schema.json' and they can be saved in subfolders within the json folder.
      • openapi (folder): Contains openapi schemas. The files in this folder have the .yml extension and they can have any name, for example: 'my_new_openapi_schema.yml'.
        • default_response (folder): Contains openapi schemas for koa2 default response (200, 201, 401, 404, 500).
        • json_web_token (folder): Contains openapi schemas for token (json web token) and create token.
        • secutiry (folder): Contains openapi schema for authentication with bearer token.
        • user (folder): Contains openapi schema for user.
    • types.d.ts (file): Includes any types used by the project, for example type Orm, JsonSchema, Module augmentation (Koa), etc. You can call the Orm/JsonSchema/others type using jsdoc, for example: /*_ @type {import('route/to/typesfolder/types.d.ts').Orm} _/
    • api.js (file): Creates and configures the Koa object and it exports the Koa object.
    • server.js (file): Mounts the API and runs the server.

• If you do not want to use openapi.

  • Delete the api/src/schemas/openapi folder.
  • Delete the api/src/config/openapi.js file.
  • Delete the api/src/routes/swagger folder.
  • In the api/src/routes/index.js file, delete:

    if (environment !== 'production') {
      router.use('/docs', swaggerRouter.routes())
    }

  • In terminal use:

      cd api
      npm uninstall openapi-comment-parser

  • delete api-specification.yml
  • Remove the openapi comment in the files in api/src/routes, for example:

      /**
        * GET /api/v1/users/{userEmail}
        *
        * @tag API endpoints
        * @security BearerAuth
        * @summary Get an user by email
        * @pathParam {string} userEmail
        * @response 200 - Ok
        * @responseContent {User} 200.application/json
        * @response 401 - Unauthorized
        * @responseComponent {Unauthorized} 401
        * @response 404 - Not found
        * @responseComponent {NotFound} 404
        * @response 500 - Internal Server Error
        * @responseComponent {InternalServerError} 500
      */
      router.get('/:userEmail', async (ctx) => {

    This comment begin with GET, POST, PUT or others HTTP Verb.

• If you do not want to use JSON Schemas.

  • Delete the api/src/schemas/json folder.
  • In terminal use:

      cd api
      npm uninstall ajv ajv-errors ajv-formats globs

  • Delete in files api/src/routes/user/registerRouter.js, api/src/routes/user/router.js and api/src/routes/authentication/tokenRouter.js

    import { simpleJsonSchemaValidation } from '../../schemas/json/index.js'

Added docker support:

When the Docker support is activate (--useDocker is used), the following files are added to default project in api folder:

• .dockerignore (file): Files and folders ignore to Docker.
• Dockerfile (file): Used to create a docker image.
• docker-entrypoint.sh (file): Contains scripts to run migrations in development mode. Used by ENTRYPOINT in Dockerfile.
• wait-for-it.sh (file): More information, see wait-for-it.sh in github. Script used to wait for the database to be enabled to receive connections.

Added docker compose support:

When the Docker Compose support is activate (--useDockerCompose is used), the following files and folders are added to default.

• api/.env (file): Adds the values ​​corresponding to the database environment variables, for example for postgresql, adds the following environment variables:

  DB_USERNAME=admin
  DB_PASSWORD=admin
  DB_NAME=api
  DB_HOST=database
  DB_PORT=5432
  DB_DIALECT=postgres

  DATABASE_URL=postgresql://admin:admin@database:5432/api

• database (folder): Contains files used to create and cofigure the database.

  • .dockerignore (file): Files and folders ignored by docker.
  • .env (file): Environment variables used the database in docker.
  • .env.example (file): Contains an example of database environment variables used to create a .env file.
  • Dockerfile (file): Used to create docker image.

• In the root folder:

  • docker-compose.yml (file): Used to deploy the docker container (API and database), contains the volumen and environment variables used by the API and database, publish the API ports, etc.
  • .env (file): Contains the environment variables to configure docker-compose.yml file.
  • .env.example (file): Contains an example of docker-compose.yml environment variables used to create a .env file.

Generators included

The generators included are:

koa2-api-generator:app used by yo koa2-api-generator: It is the generator used by default.

koa2-api-generator:docker: It is used to add support for Docker. It accepts the options --useDocker, --nodeVersion and --projectFolderName.

koa2-api-generator:docker_compose: It is used to add support for Docker Compose. It accepts the options --useDockerCompose and --databaseName.

The question: Do you want to automatically run the scripts that configure the package, then installing the dependencies?

When you selects the true value, the following scripts ubicated in the package.json are executed:

• init
• format:fix

If you selects the false value, if you want to use husky, you must run npm run init.

The scripts in package.json

The more important scripts added into the package.json created by this generator are:

• "init": Runs the commands necessary to initialize the package, for example init:husky.
• "dev": Runs the application in development mode using nodemon and dotenv.
• "start": Runs the application using node.
• "format": Checks the format using prettier.
• "format:fix": Fixes the format using prettier.
• "lint": static code analysis using eslint.
• "lint:fix": Fixes the code using eslint.
• "commitlint": Runs commitlint. It is used into .husky/commit-msg file. It is called by the commit-msg hook. See git hook.
• "lint-staged": Runs lint-staged. It is used into .husky/pre-commit file. It is called by the pre-commit hook. See git hook.
• "quality-check": Runs npm run format && npm run lint. It is used into .husky/pre-push file. It is called by the pre-push hook See git hook.

Getting To Know Yeoman

• Yeoman has a heart of gold.
• Yeoman is a person with feelings and opinions, but is very easy to work with.
• Yeoman can be too opinionated at times but is easily convinced not to be.
• Feel free to learn more about Yeoman.

Author Author

👤 Cristopher Jiménez Meza

• Github: @cristopher1

🤝 Contributing

Contributions, issues and feature requests are welcome!
Feel free to check issues page. You can also take a look at the contributing guide.

Show your support

Give a ⭐️ if this project helped you!

📝 License

Copyright © 2024 Cristopher Jiménez Meza.
This project is MIT licensed.

---