This KSTARTER template is part of a suite of Node.js project starters, configured with Express.js, TypeScript, Mongoose, and JWT authentication via secure cookies. It is designed to provide a robust API backend for a variety of Node.js applications.

Features

• ⚡️ ExpressJS
• 📚 Database with MongoDB and ODM via Mongoose
• 🔐 Auth Management with JWT (Secure Cookie)
• ✅ Type checking TypeScript with strict mode
• 🧙 Live reload
• ⚙️ Environment variable with dotenv
• 📦 Docker support (Dev and Production)
• 🤖 Testing with Jest
• 🚀 Ready for fast development
• ✉ Resend for reliable email sending

Prerequisites

Before you begin, ensure you have installed the following:

• Node.js (v20.x or higher)
• npm
• MongoDB (local, remote or docker)

Getting Started

Copy project files in a new directory and detach from the current git repository.

git clone https://github.com/kevinfavv/KStarter-mongoose-express-ts.git <project folder name>
cd <project folder name>
rm -rf .git

Install dependencies in the project directory.

npm run install

Create dotenv file from a copy of .env.example

cp .env.example .env

Generate JWT Private and Public key.

./scripts/generateAuthKeys.sh

this will automatically create a folder named auth with two files inside private.pem and public.pem and add keys in .env

Then, you can run the project with the following command:

npm run dev

Env file specifications

• NODE_ENV
• APP_NAME : Your app name
• PORT : Port for the server
• COOKIE_DOMAIN : Domain for the cookie No port! example : localhost for allow localhost:5173 (host) : If not set correctly, Browsers will not save cookies
• CORS_ORIGIN : Allowed origin for CORS
• JWT_ISSUER : JWT Issuer name
• JWT_TTL : Time to live in seconds (Usually between 15 and 60 minutes.)
• REFRESH_TOKEN_TTL : The maximum time in seconds the user remains logged in if they return to the page. (Usually a few days)
• MONGODB_URL : MongoDB connection string
• MONGODB_DB_NAME : MongoDB database name
• PUBLIC_KEY : Auto-generated when you call ./scripts/generateAuthKeys.sh
• PRIVATE_KEY : Auto-generated when you call ./scripts/generateAuthKeys.sh

JWT Cookies

Backend Auth Check

By default all the routes you will make in src/Routers/ApiRouter.ts are secured by JWT, users must be logged in to access them. If you want more control just remove the AuthMiddleware in src/app.ts and add it on the routes you want in the router.

FrontEnd

On your front application, you must send the “withCredentials” parameter on each request.

More info here : https://developer.mozilla.org/en-US/docs/Web/API/XMLHttpRequest/withCredentials

Exemple with Axios

// Create axios instance
const instance = axios.create({
    baseURL: '{{BASE_URL_FOR_YOUR_API_HERE}}',
    withCredentials: true, // Send cookies !
});

// This request will send the cookies to the server
axios.get('/api/protected_path')
    .then((response) => {
        console.log(response.data);
    })
    .catch((error) => {
        console.error(error);
    });

Auth Issues

😥 Unable to connect, cookies are not saved in my browser

• Check that you have added the domain in your .env file in COOKIE_DOMAIN. Please note, only domains (hosts) are valid. no PORT number
• Check that you have sent your request with the withCredentials parameter (example above)

Docker Compose

💡 dev.Dockerfile is not perfoming any build or dependency installation, it is only copying the files to the container. This is useful for development purposes, as it allows you to use the host's node_modules folder and have live reload.

version: '3.8'

services:
  mongodb:
    container_name: mongodb
    image: mongo:latest
    ports:
      - "27017:27017"
    volumes:
      - {{YOUR_MONGO_LOCAL_SAVE_FOLDER}}:/data/db
    environment:
      MONGO_INITDB_ROOT_USERNAME: root
      MONGO_INITDB_ROOT_PASSWORD: example
    networks:
      - apiNetwork

  api:
    container_name: api
    depends_on: ['mongodb']
    volumes:
      - ./:/usr/src/app
    build:
      context: .
      dockerfile: dev.Dockerfile
    env_file:
      - ".env"
    environment:
      NODE_ENV: development
    ports:
      - 4000:4000
    networks:
      - apiNetwork

networks:
  apiNetwork:
    driver: bridge

Contributing

Contributions are welcome! Please read our Contributing Guide for details on our code of conduct and the process for submitting pull requests to us.

License

This project is licensed under the MIT License - see the LICENSE.md file for details.