Express + Typescript REST API Template

This repository provides a basic structure for building REST APIs using Express and TypeScript. It includes essential configurations and dependencies required to help you get started quickly and securely.

Features

• Express server setup with TypeScript
• Basic middleware configuration (CORS, JSON parsing, global error handler)
• Zod for object validation (DTOs, etc.)
• Support for custom API errors, including validation errors that are easily instantiated using errors thrown by Zod
• Pre-configured ESLint and Prettier for code quality and formatting
• Commit hooks that run ESLint and Prettier, configured using the Husky library
• Environment management with dotenv and config/env.ts, which validates each environment variable
• Testing with jest
• Basic folder structure for organizing and versioning your API

Getting Started

Prerequisites

• Node.js (v18 or higher)
• pnpm (of course you can use whichever package manager you want, but pnpm is highly recommended)

Installation

1. Clone the repository:

git clone https://github.com/caiohperlin/rest-api-express-template.git
cd rest-api-express-template

2. Install dependencies:

pnpm install

3. Create a .env file in the root directory and add your environment variables:

PORT=5000
NODE_ENV=development

Available Scripts

Development

• pnpm dev - Start the development server with hot reload using tsx
  • Watches for file changes and automatically restarts the server
  • Runs directly from TypeScript source files

Production

• pnpm start - Start the production server

  • Runs the compiled JavaScript files from the dist directory
  • Make sure to run pnpm build first

• pnpm build - Build the project for production

  • Compiles TypeScript to JavaScript using tsc
  • Resolves path aliases using tsc-alias
  • Output is generated in the dist directory

Code Quality

• pnpm typecheck - Run TypeScript type checking without emitting files

  • Useful for CI/CD pipelines or quick type validation
  • Faster than full compilation

• pnpm lint - Run ESLint on the source code

  • Checks for code quality issues and potential bugs
  • Covers .ts and .js files in the src directory

• pnpm lint:fix - Run ESLint and automatically fix issues

  • Same as lint but attempts to fix auto-fixable problems

Formatting

• pnpm format - Format all files using Prettier

  • Applies consistent code formatting across the project
  • Modifies files in place

• pnpm format:check - Check if files are properly formatted

  • Useful for CI/CD to ensure code is formatted
  • Exits with error code if formatting is needed

Testing

• pnpm test - Run all tests using Jest

  • Includes --passWithNoTests flag for projects without tests yet
  • Runs once and exits

• pnpm test:watch - Run tests in watch mode

  • Automatically re-runs tests when files change
  • Interactive mode for development

• pnpm test:coverage - Run tests with coverage report

  • Generates detailed coverage reports
  • Useful for understanding test coverage metrics

Git Hooks

• pnpm husky:prepare - Initialize Husky git hooks
  • Sets up pre-commit hooks
  • Automatically runs during pnpm install

Development Workflow

1. Start development: pnpm dev
2. Make changes: Edit files in the src directory
3. Run tests: pnpm test or pnpm test:watch
4. Check code quality: pnpm lint and pnpm format:check
5. Commit changes: Git hooks will automatically run linting and formatting
6. Push changes

Production Deployment

1. Build the project: pnpm build
2. Start production server: pnpm start
3. Environment variables: Ensure all required environment variables are set in your production environment

Project Structure

rest-api-express-template/
├── .husky/                # Git hooks configuration
├── dist/                  # Compiled files (generated)
├── node_modules/          # Node.js modules
├── src/                   # Source files
│   ├── api/               # API related files
│   │   └── v1/            # Version 1 of the API
│   │       ├── app/       # Example app module
│   │       └── index.ts   # v1 Router
│   ├── config/            # Configuration files
│   │   └── env.ts         # Environment variables validation
│   ├── errors/            # Custom error classes
│   ├── middleware/        # Custom middleware
│   ├── utils/             # Utility functions
│   ├── app.ts             # Express application config
│   └── server.ts          # Project entry point
├── .env                   # Environment variables
├── .env.example           # Environment variables template
├── .lintstagedrc.json     # lint-staged configuration
├── eslint.config.mjs      # ESLint configuration
├── jest.config.js         # Jest testing configuration
├── package.json           # Project dependencies and scripts
├── pnpm-lock.yaml         # pnpm lock file
├── prettier.config.js     # Prettier configuration
├── README.md              # Project documentation
└── tsconfig.json          # TypeScript configuration

Git Hooks

This project uses Husky to manage Git hooks:

• Pre-commit: Runs ESLint and Prettier on staged files only

Contributing

Feel free to fork this repository and make your own changes. Pull requests are welcome!

License

This project is licensed under the ISC License.

Thank you for reading and happy express-ing! 👾