Typescript Express Mongoose Starter

A professional, well-structured TypeScript Node.js API built with Express and MongoDB (Mongoose). This project is designed as a clean starter for building production-grade REST APIs with TypeScript, strong typing, validation, centralized error handling, and sensible defaults for pagination, filtering and searching.

Key highlights

• TypeScript-first codebase with strict compiler settings
• Express for HTTP routing and middleware

Table of contents

• Project status
• Tech stack
• Quick start

Project status

• Version: 2.0.0

Tech stack

• Node.js + TypeScript
• Express

Quick start

1. Clone the repository and install dependencies

git clone https://github.com/md-abu-kayser/typescript-express-mongoose-starter.git

2. Create environment file(s)

This project loads environment variables using dotenv. Copy or create an .env file at the repository root. Example values:

3. Run in development (auto-reload)

npm run start:dev

## Environment variables

- PORT (required) - HTTP port the server will listen on
- DATABASE_URL (required) - MongoDB connection string

## Available npm scripts

- `npm run start:dev` - Start the app in development using `ts-node-dev` (auto-reload)
- `npm run start:prod` - Run the built production bundle (`node dist/server.js`)

## How the app starts

- Entry point for development: `src/server.ts` - connects to MongoDB then starts the Express app.
- Main Express application: `src/app.ts` - registers middleware, health check and routes.

GET /health

API Reference - Students

Base path: /api/v1/students

1. Create a student

• POST /
• Body shape: { student: { ... } }

2. Get students (list)

• GET /
• Query params supported:

3. Get single student

• GET /:studentId
• Returns 200 and the student document, or 404 if not found.

4. Update student

• PATCH /:studentId
• Body shape: { student: { ...fieldsToUpdate } }

5. Delete student (soft delete)

• DELETE /:studentId
• Soft deletes the record by setting isDeleted: true and returns the updated document.

Student data model

Key fields (see src/app/modules/student/student.interface.ts and student.model.ts):

Validation

Request validation uses Zod schemas (src/app/modules/student/student.validation.ts) and the validateRequest middleware (src/app/middlewares/validateRequest.ts).

Error handling

• AppError (src/app/utils/AppError.ts) is used to create operational errors with a status code.
• globalErrorHandler (src/app/middlewares/globalErrorHandler.ts) serializes errors and sends a consistent JSON error envelope.

Project structure---> important files

• src/server.ts - app bootstrap, DB connection and process-level error handling
• src/app.ts - Express initialization, global middleware, and route mounting

Tests

Unit and integration tests can be written using Jest (configured in package.json). Example:

Contributing

Contributions are welcome. A recommended workflow:

Deployment notes

• Ensure NODE_ENV=production and supply a secure DATABASE_URL when deploying.
• Build (npm run build) before starting the production process.

License

• This project is licensed under the terms of the MIT License.
• You may replace or update the license as needed for client or proprietary projects.

---

Contact and Maintainer

Maintainer: md-abu-kayser
Name: Md Abu Kayser - Full-Stack Engineer

• GitHub: github.com/abu.kayser-official
• Email: abu.kayser.official@gmail.com
• Project: typescript-express-mongoose-starter

If you’d like this README tailored for a specific purpose - such as hiring managers, open-source contributors, or client deliverables - feel free to request a custom tone or format.

---

Thank You For Reviewing This Project!

---