This boilerplate project encompasses a range of common requirements for node API development, combining technologies such as Express, TypeScript, PostgreSQL, and Password-JWT. The following features are implemented:

• Express Server: Express server is in place with most of reuqired middlewares.
• PostgreSQL Integration: Seamless integration with a PostgreSQL database.
• Authentication and Authorization: Utilizes JSON Web Tokens (JWT) with password-based authentication.
• Session Management : Common requirements for session handling are already in place.
• View Engine: View engine with EJS is in place for public and private pages with actions.
• CRUD Operations: Routes to handle Create, Read, Update, and Delete operations.
• Testing: Includes setups for unit tests, integration tests, and end-to-end tests.
• Documentation: Features an OpenAPI specification for API documentation.
• Swagger UI: Provides a Swagger UI setup for easy API exploration.
• Docker and Docker-Compose: Docker and Docker-Compose setups for containerization with pm2 for production.
• Logging: Configured Morgan for HTTP logging and Winston for application level logging.

• Authentication Service:

  • Provides API endpoints to handle user authentication + authentication and basic CRUD operations on user which can be extended to fully functioning authentication service.

• Login Portal:

  • Provides user interfaces for login, registration, and private pages with session management which can be extended to feature rich universal login platorm.

Feel free to use this boilerplate project for kickstarting your web development endeavors.

• Prerequisites
• Getting started
  • Quick start
  • Dev setup
• Environment variables
• Project structure
• Build scripts
• Debugging
• Logging
• Testing
  • Integration tests with Supertest
  • Unit tests with Jest
  • E2E tests with Cypress
• Code analysis and Fomatter
  • Linting
  • Formatting
• Documentaion
• Dependencies
  • production
  • development
• License

• Node v18+ Node.js

# Get the latest snapshot
git clone --depth=1 https://github.com/imchamarac/jwt-auth-service.git <project_name>

# Change directory
cd <project_name>

# Copy the .env.example contents into the .env
cat .env.example > .env

There are two ways to go about running this project in your dev enviornment. You can either follow the quick start path where you can use the docker-compose setup or you can setup the development enviornment by following the steps in dev setup.

Ensure you have docker installed on your machine or you can install it from Docker.

You can simply run the docker-compose up command to build and runs the following required services.

• pgadmin - Database administrator tool
• db - PostgreSQL database
• app - Express server instance

Once docker compose is completed building process and starts running you can follow the below setps to setup the pgAdmin tool

• Go to http://localhost:5050/browser/ in your browser.
• Use the credentials under the pgadmin service in the docker compose file to login.
• Once you're logged in, create a new server by right click on the Server -> Register -> Server
  • General tab - provide the server name (any name)
  • Connection tab - provide db as the host name/ address and fill password from the docker compose file
• If you navigate to DB name(jwt_auth_service default) -> Schemas -> Tables -> users table should be available
• Database is up and running and is ready to accept connections from our application.

You can check the database service by running the following commands:

• docker exec -ti pg_server /bin/bash - to start a interactive terminal inside the container.
• psql jwt_auth_service admin - to log into the database with admin role.
• \dt - to list avilable tables.
• SELECT * FROM users; - to list users from the users table.

With that you now have access to your API 🎉 🎉 🎉 🎉

• Go to http://localhost:8080/login to visit the web application and you can start by registering a new user

• Go to http://localhost:8080/api/v1/docs/ to check the swagger docs

• Go to Postman and start sending API requests to listed endpoints in the swagger docs

If you would like to run this project in dev mode to play around with the codebase, I recommend setting it up using the following steps.

You can install postgreSQL by running:

brew install postgresql

Export the following environment variables from the root:

export PGUSER=admin
export PGPASSWORD=password
export PGDATABASE=jwt_auth_service
export PGHOST=localhost
export PGPORT=5432

The database schema and seed data is located inside the db folder.

Run following command to create database schema:

psql -f ./db/schema.sql

(optional) If you are planning to run integration tests:, run the following command to create a test database:

psql -f ./db/schema-test.sql

(optional) Run following command to seed the database:

psql -f ./db/data.sql

To run the migrations use the following command (after you have installed all packages):

db-migrate up

You can skip this step if you already have a configured database admin tool, if not you can download and setup DBeaver to help you to visualize and manage your databases.

Once you created and connected to a server, you can start the application in your local environment

Before start the dev server install dependencies by ruiing yarn install.

Once the installation is completed, you can start the application by ruuning yarn dev...

With that you now have access to your API with live reloading 🔥 🔥 🔥 🔥

• Go to http://localhost:8080/login to visit the web application and you can start by registering a new user

• Go to http://localhost:8080/api/v1/docs/ to check the swagger docs

• Go to Postman and start sending API requests to listed endpoints in the swagger docs

Happy coading folks 👨‍💻 👩‍💻

npm scripts can be found in package.json in the scripts section.

Follow below steps if you want to run in the debug mode,

• To start debug mode run dev:debug script.
• Press Ctrl+Shift+P and find the Debug: Attach to Node Process command from the command palette of VScode.
• Now you can add breakpoints and send a request from the browser or from the postman.

We're using following libraries to handle application's loggings

• Morgan - to log incoming HTTP requests
• Winston - to log application errors, info, warnings and debugging.

This project uses Jest for unit tests, Supertest for integration tests and Cypress for E2E tests the web pages.

We use a separate database to run integration tests so we can keep it clean after each tests.

If you haven't done already, run the following command to create a test database:

psql -f ./db/schema-test.sql

After creating the test database, you can run the following script to run integration tests

test:integration

Run the following command to run unit tests:

test:units

Run the following command to run cypress tests:

test:e2e

This project is using ESLint with typescript-eslint/recommended settings for static code analysis.
Run lint:fix to scan and fix(what's fixable) problematic patterns in your code.

This project is using Prettier for code formatting. Run prettier:fix to scan and fix formatting issues.

This project uses openapi 3 specification with swagger express UI to render the documents into api/v1/docs route.

Note that I've used two methods(inline and separate folder) to write docs and used jsDOC to switch and load them into the swagger express UI.

Feel free to use only one method that you prefer.

The MIT License (MIT)

Copyright (c) 2024 Chamara Chathuranga

Permission is hereby granted, free of charge, to any person obtaining a copy of this software and associated documentation files (the "Software"), to deal in the Software without restriction, including without limitation the rights to use, copy, modify, merge, publish, distribute, sublicense, and/or sell copies of the Software, and to permit persons to whom the Software is furnished to do so, subject to the following conditions:

The above copyright notice and this permission notice shall be included in all copies or substantial portions of the Software.

THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.