Skip to content

cristopher1/generator-express-simple-api-generator

Repository files navigation

Welcome to generator-express-simple-api-generator 👋

Version Documentation Maintenance License: MIT

Yeoman generator to create a simple base structure for api rest based on express framework.

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

Based on generator-koa2-simple-api-generator

The project generated by generator-express-simple-api-generator use ES Modules and async/await functions.

Example of a generator created by generator-express-simple-api-generator:

project-generated-by-generator-express-simple-api-generator

Installation

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

npm install -g yo
npm install -g generator-express-simple-api-generator

Then generate your new project:

yo express-simple-api-generator project_name

Prerequisites

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

yo express-simple-api-generator project_name

Example:

PS C:\Users\...\new_express_api_project> yo express-simple-api-generator project_name

Arguments and options

The generator-express-simple-api-generator include one argument called projectName. projectName is a required argument:

For example: If you want to create a new express api called express_api_project (projectName = express_api_project), you should use:

yo express-simple-api-generator express_api_project

The generator-express-simple-api-generator include various options, these are:

option value default description example
runGitInit Boolean false Run git init automatically, then installing the dependencies yo express-simple-api-generator project_name --runGitInit
runPackageScripts Boolean false Run the scripts that configure the package, then installing the dependencies yo express-simple-api-generator project_name --runPackageScripts
useDocker Boolean false Add docker support using DockerFile, .dockerignore and others yo express-simple-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 express-simple-api-generator project_name --nodeVersion=21
projectFolderName String api Project folder name used in DockerFile. (WORKDIR /usr/src/projectFolderName) yo express-simple-api-generator project_name --projectFolderName=project_folder_name
useDockerCompose String false Add Docker Compose support. yo express-simple-api-generator project_name --useDockerCompose
databaseName String null Select the database to which the application will connect. Accepts the values: postgresql, mysql, mariadb and mongodb. yo express-simple-api-generator project_name --databaseName=postgresql

Project structure

The project generated by generator-express-simple-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.
    • commitlint.config.js (file): Congiguration used by commitlint.
    • package.json (file): Contains dependencies, dev dependencies, scripts, etc.
    • README.md (file): Documentation generated by generator-express-simple-api-generator.
    • src (folder): Contains the source code:
      • config (folder): Contains configuration files, for example database.js (contains environment varibles used by sequelize) and jwt.js (contains environment variables used by jsonwebtoken).
      • routes (folder): Contains the Express routers used by the project.
        • authentication (folder): Contains functions and routers to authenticate the users with json web token.
        • user (folder): Contains functions and routes to register, obtain and modify an user. Uses default model user
        • index.js (file): Contains the main Express router and mounts the others routers.
      • api.js (file): Creates and configures the Express object and it exports the Express object.
      • server.js (file): Mounts the API and runs the server.

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

  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:

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

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

express-simple-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

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


This README was generated with ❤️ by readme-md-generator