https://github.com/caiohperlin/rest-api-express-template
Simple development-ready Express + TypeScript REST API template!
https://github.com/caiohperlin/rest-api-express-template
api backend boilerplate commit-hooks eslint express folder-structure husky jest node nodejs rest template typescript
Last synced: 23 days ago
JSON representation
Simple development-ready Express + TypeScript REST API template!
- Host: GitHub
- URL: https://github.com/caiohperlin/rest-api-express-template
- Owner: CaioHPerlin
- Created: 2025-03-13T20:35:05.000Z (10 months ago)
- Default Branch: development
- Last Pushed: 2025-06-18T19:54:51.000Z (7 months ago)
- Last Synced: 2025-06-25T22:44:44.738Z (7 months ago)
- Topics: api, backend, boilerplate, commit-hooks, eslint, express, folder-structure, husky, jest, node, nodejs, rest, template, typescript
- Language: TypeScript
- Homepage:
- Size: 155 KB
- Stars: 0
- Watchers: 1
- Forks: 0
- Open Issues: 0
-
Metadata Files:
- Readme: README.md
Awesome Lists containing this project
README
# 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:
```bash
git clone https://github.com/caiohperlin/rest-api-express-template.git
cd rest-api-express-template
```
2. Install dependencies:
```bash
pnpm install
```
3. Create a `.env` file in the root directory and add your environment variables:
```bash
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! 👾