npm package discovery and stats viewer.

Discover Tips

  • General search

    [free text search, go nuts!]

  • Package details

    pkg:[package-name]

  • User packages

    @[username]

Sponsor

Optimize Toolset

I’ve always been into building performant and accessible sites, but lately I’ve been taking it extremely seriously. So much so that I’ve been building a tool to help me optimize and monitor the sites that I build to make sure that I’m making an attempt to offer the best experience to those who visit them. If you’re into performant, accessible and SEO friendly sites, you might like it too! You can check it out at Optimize Toolset.

About

Hi, 👋, I’m Ryan Hefner  and I built this site for me, and you! The goal of this site was to provide an easy way for me to check the stats on my npm packages, both for prioritizing issues and updates, and to give me a little kick in the pants to keep up on stuff.

As I was building it, I realized that I was actually using the tool to build the tool, and figured I might as well put this out there and hopefully others will find it to be a fast and useful way to search and browse npm packages as I have.

If you’re interested in other things I’m working on, follow me on Twitter or check out the open source projects I’ve been publishing on GitHub.

I am also working on a Twitter bot for this site to tweet the most popular, newest, random packages from npm. Please follow that account now and it will start sending out packages soon–ish.

Open Software & Tools

This site wouldn’t be possible without the immense generosity and tireless efforts from the people who make contributions to the world and share their work via open source initiatives. Thank you 🙏

© 2024 – Pkg Stats / Ryan Hefner

generator-koa2-api-generator

v1.0.2

Published

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

Downloads

2

Readme

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:

generator-koa2-api-generator-project

Index

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

🤝 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.