Template API using ExpressJS

Setup project locally

Setup development environment

1. Clone this project (or use it as template to create another repository inside the GitHub)
2. Open the project's directory either on a terminal or inside an IDE (like Visual Studio Code)
3. [Follow this step only if you opened the project inside the IDE] Open a terminal inside the IDE
4. Run the command nvm use. This command gets the node's version located inside the .nvmrc file and use it inside the terminal.
5. Run the command npm i in order to install all dependencies and devDependencies.
6. Copy-Paste the content of the .env.example inside the git-ignored .env file.

Setup the app's information

Package.json

Inside the package.json file you can modify the following key-value pairs with your app's (api) information:

1. "name"
2. "version"
3. "description"
4. "keywords"
5. "homepage"
6. "bugs"
7. "repository"
8. "license"
9. "author"

You could also add scripts that you want inside the scripts object of the package.json file.

docker-compose.yml

Inside the docker-compose.yml file you can modify the following values inside the postgres database container configuration.

• Inside the services configuration you can change the name of the postgres database service (mainDb) to whatever you want as database docker container's service name.
• As container name for the service mainDb (container_name: api_dev_db) you could change the api_dev_db to whatever you want as the service's docker name.
• Also you could modify the api_dev_db inside the volumes configuration to whatever you want (don't forget to change it inside the mainDb's service volumes and general volumes configuration inside the docker-compose file both).

.env.example / .env (Environment Variables files configuration)

Inside the .env.example and .env files you could find the following environment variables already configured:

• NODE_ENV: This variable could only get three (3) values, development | production | test, depends on the running environment for the API. If you run the API locally, then prefer the development value. For testing purposes prefer the test value and for the production deployment use the production value.
• APPLICATION_NAME: This variable contains the application's name that will also appears to every response as copyrighting process.
• APPLICATION_PROVIDER: This variable contains the application's provider (usually the company or the organization that develops or developed for the current API).
• HOME_PAGE_URL: This variable contains the application's or provider's homepage url.
• SERVER_PROT: The port that the server runs (default and suggested for the BackEnd API is 8080).
• BACKEND_URL: The URL that the API runs (use either the locally distributed link -for the localhost- or the production's link).
• BACKEND_API_URL: The URL that the API runs (use either the locally distributed link -for the localhost- or the production's link). This should also contains the prefix for the api routes-endpoints.
• SESSION_SECRET: This variable contains a unique string with more than 32 characters inside it (suggested format is a UUID string) that is used by the system to establish the decryption of the express session's cookie.

The following Environment Variables also being used by the docker compose file to construct the mainDb service:

• POSTGRES_HOST: Host for Postgres database (use localhost, IPv4, IPv6 or a physical address domain like https://tsalmas.com).
• POSTGRES_PORT: Network port that exported by the Postgres database and used by the docker services and the current API infrastructure to establish connection using Sequelize ORM for the database.
• POSTGRES_USER: Authorized user that have admin or permitted/limited access and used by the system to execute queries inside the database.
• POSTGRES_PASSWORD: Password for authorized user as explained before. You could also leave it blank if your user is root and doesn't have password to be authorized for the database usage. It is not suggested to leave it blank for production purposes, only for development environment.
• POSTGRES_DB: Database name.
• DB_DIALECT: This is used by Sequelize ORM to configure dialect being used by the ORM to setup the queries. For PostgresDB the value should be postgres. For other values, you could search here.
• DB_MIGRATION_STORAGE: This variable's value used by Sequelize ORM to define storage for migrations. Leave it as is sequelize, is the suggested option.
• DB_MIGRATION_STORAGE_TABLE_NAME: This variable is define the table name that is been created inside the database and saved the executed migrations. You could modify it what whatever value you want.
• DB_SEEDER_STORAGE: This variable's value used by Sequelize ORM to define storage for seeders. Leave it as is sequelize, is the suggested option.
• DB_SEEDER_STORAGE_TABLE_NAME: This variable is define the table name that is been created inside the database and saved the executed seeders. You could modify it what whatever value you want.

You could also add whatever variable you want to add inside.

server/src/app.ts

You could modify with your own copyrighting the code block that runs when the server is starting (<express-server>.listen(...)).

Run the app

Locally

nvm use
npm run server:dev

You can see you app running on port defined inside the environment variables inside the file .env. You could now ping to https://<server-address>:<SERVER_PORT>. If the configured port is already taken by another procedure in you system, the server will fail to start and open.

Build for production

nvm use
npm run server:prod

You can see you app running on port defined inside the environment variables inside the file .env. You could now ping to https://<server-address>:<SERVER_PORT>. If the configured port is already taken by another procedure in you system, the server will fail to start and open.

Handle the ORM actions

Before you run any script, please be positive that you already created the directories:

• server/src/db/migrations This directory saves the migrations for database
• server/src/db/seeders This directory saves the seeders for database (seeding mock data)
• server/src/models This directory saves the Sequelize entities/models, for example create a user.model.ts file to create User entity/sequelize model.

Migrations using the Sequelize CLI

Create migration file (this file is being created in JavaScript dialect and not Typescript)

nvm use
npm run db:create:migration <migration-name-here>

Execute all the migrations for the database

nvm use
npm run db:migrate

Undo migrations

• Undo a specific migration

nvm use
npm run db:migrate:undo <migration-name-here>

• Undo all the migrations

nvm use
npm run db:migrate:undo:all

Seeding using the Sequelize CLI

Create seeding file (this file is being created in JavaScript dialect and not Typescript)

nvm use
npm run db:create:seed <seeder-name-here>

Execute all the seeders for the database

nvm use
npm run db:seed

Undo seeders

• Undo a specific seeder

nvm use
npm run db:migrate:undo <seeder-name-here>

Validate input data

In order to validate the input data, this system uses Zod validation. You can create a validation schema using Zod suggested schema ways and use the inputValidation middleware in route definition as middleware giving the zod schema to be validated.

Provided npm scripts

• server:dev: Runs the app locally (for development environment).
• server:prod: Runs the deployed production server.
• db:create:migration: Create a migration file.
• db:migrate: Execute created and not executed -yet- migrations.
• db:migrate:undo: Undo a specific migration. This migration should be executed.
• db:migrate:undo:all: Undo all executed migrations at once.
• db:create:seed: Create a seeder file.
• db:seed: Execute created and not executed -yet- seeders.
• db:seed:uno: Undo a specific seeder. THis seeder should be executed first.
• format: Checks if the code format complies with prettier's configured rules.
• format:fix: Fixes the format of the code to comply with prettier's rules.
• lint: Checks if the code quality complies with eslint's configured rules.
• lint:fix: Fixes the format of the code to comply with eslint's rules.
• tsc: Checks the typescript compliance inside the application's code.
• test: Script to run tests. Tests are not configured yet and this script too.
• prepare: Configure the husky git's custom scripts. The pre-push script is already created by this template.

Important rules

Core modules documentation

The structure of the app follows at 100% of the environment the documentations listed for modules that used by the system (for versions listed inside the package.json file):

• Node
• Express.js
• Express-Session
• Sequelize
• Pino logger
• Zod

Project structure

The structure of the project is your choice but the recommended is the following (for server/src):

(idea from bulletproof react)

src
|
+-- controllers             # controllers for each route
|
+-- routes                  # application routes / can also be pages
|
+-- assets                  # assets folder can contain all the static files such as images, fonts, etc.
|
+-- config                  # global configurations, exported env variables etc.
|
+-- hooks                   # shared hooks used across the entire application
|
+-- services                # reusable libraries preconfigured for the application
|
+-- stores                  # global state stores
|
+-- testing                 # test utilities and mocks
|
+-- types                   # shared types used across the application
|
+-- utils                   # shared utility functions
|
+-- middlewares             # shared middleware functionality
|
+-- interfaces              # application interfaces
|
+-- helpers                 # shared helpers functionality
|
+-- schemas                 # schemas for input validation using Zod