create-express-pg-api

A reusable backend project generator for quickly creating a TypeScript API with Express, PostgreSQL, TypeORM, authentication, Redis, validation, file uploads, and common backend utilities.

Quick Start

Create a new backend project with:

pnpm create express-pg-api my-project

Move into your new project:

cd my-project

Create your environment file:

cp .env.example .env

Update the required environment variables, then start development:

pnpm dev

Features

The generated backend includes:

• Node.js
• TypeScript
• Express.js
• PostgreSQL
• TypeORM
• Redis
• JWT authentication
• Access and refresh tokens
• bcrypt password hashing
• class-validator
• class-transformer
• Request validation middleware
• Global error handling
• Not-found middleware
• Rate limiting
• File upload middleware
• Cloudflare R2 integration
• Base entity
• Base service
• User module
• Authentication module
• Media module
• Organized API routing
• Environment configuration
• Custom Express request types

Usage

Generate a new project:

pnpm create express-pg-api my-api

Example:

pnpm create express-pg-api ecommerce-api

The generator will automatically:

1. Create the project directory
2. Copy the backend starter template
3. Update the project name in package.json
4. Create .gitignore
5. Include .env.example
6. Install dependencies using pnpm
7. Prepare the project for development

Generated Project Structure

my-project/
├── src/
│   ├── common/
│   │   ├── entites/
│   │   │   └── base.entity.ts
│   │   ├── media/
│   │   │   └── media.map.ts
│   │   └── services/
│   │       └── base.service.ts
│   │
│   ├── configs/
│   │   ├── db/
│   │   │   └── db.ts
│   │   ├── cors.ts
│   │   ├── r2.config.ts
│   │   └── redis.ts
│   │
│   ├── constant/
│   │   ├── authRequest.ts
│   │   ├── enum.constant.ts
│   │   ├── message.interface.ts
│   │   ├── rate-limitter.ts
│   │   ├── status-code.interface.ts
│   │   └── token-expiry.ts
│   │
│   ├── middlewares/
│   │   ├── authentication.ts
│   │   ├── global-error-handler.ts
│   │   ├── not-found-middleware.ts
│   │   ├── rate-limitter.ts
│   │   ├── request.validators.ts
│   │   └── upload.ts
│   │
│   ├── modules/
│   │   ├── auth/
│   │   │   ├── auth.controller.ts
│   │   │   ├── auth.route.ts
│   │   │   └── auth.service.ts
│   │   │
│   │   ├── media/
│   │   │   └── media.entity.ts
│   │   │
│   │   └── users/
│   │       ├── dto/
│   │       │   ├── sign-in.dto.ts
│   │       │   └── signup.dto.ts
│   │       ├── interfaces/
│   │       │   └── user.interaces.ts
│   │       └── user.entity.ts
│   │
│   ├── routes/
│   │   └── index.route.ts
│   │
│   ├── types/
│   │   ├── express.d.ts
│   │   └── file.upload.type.ts
│   │
│   ├── utils/
│   │   ├── ApiError.ts
│   │   ├── ApiResponse.ts
│   │   ├── async-handler.ts
│   │   ├── chalk.ts
│   │   ├── generate-uuid.ts
│   │   ├── r2Delete.ts
│   │   ├── r2Upload.ts
│   │   ├── redis.ts
│   │   └── token.ts
│   │
│   ├── app.ts
│   └── index.ts
│
├── .env.example
├── .gitignore
├── package.json
├── pnpm-lock.yaml
├── README.md
└── tsconfig.json

Environment Variables

Copy the example environment file:

cp .env.example .env

Then update the values based on your environment.

Example:

# Application
NODE_ENV=development
SERVER_PORT=5436

# PostgreSQL
POSTGRES_HOST=localhost
POSTGRES_PORT=5432
POSTGRES_USER=postgres
POSTGRES_PASSWORD=
POSTGRES_DB=

# Redis
REDIS_URL=

# JWT
ACCESS_TOKEN_SECRET=
REFRESH_TOKEN_SECRET=

# CORS
ALLOWED_ORIGINS=

# Cloudflare R2
R2_ACCOUNT_ID=
R2_ACCESS_KEY_ID=
R2_SECRET_ACCESS_KEY=
R2_BUCKET_NAME=
R2_PUBLIC_BASE_URL=

Do not commit your real .env file.

Available Scripts

Start the development server:

pnpm dev

Build the TypeScript project:

pnpm build

Run the compiled application:

pnpm start

Authentication

The starter includes an authentication structure with support for:

• User signup
• User signin
• Password hashing using bcrypt
• JWT access tokens
• JWT refresh tokens
• Authentication middleware
• User roles

Authentication files are located in:

src/modules/auth/

User-related files are located in:

src/modules/users/

Database

The generated backend uses:

• PostgreSQL
• TypeORM

Database configuration is located at:

src/configs/db/db.ts

Example entities include:

src/modules/users/user.entity.ts
src/modules/media/media.entity.ts

A reusable base entity is also included:

src/common/entites/base.entity.ts

Validation

Request validation uses:

• class-validator
• class-transformer

Validation middleware:

src/middlewares/request.validators.ts

Example DTOs:

src/modules/users/dto/sign-in.dto.ts
src/modules/users/dto/signup.dto.ts

Redis

Redis configuration is included at:

src/configs/redis.ts

Redis utility functions are located at:

src/utils/redis.ts

Configure REDIS_URL inside your .env file before using Redis-dependent functionality.

File Uploads

The starter includes file upload middleware and Cloudflare R2 integration.

Relevant files:

src/middlewares/upload.ts
src/configs/r2.config.ts
src/utils/r2Upload.ts
src/utils/r2Delete.ts

Configure your Cloudflare R2 environment variables before using file upload functionality.

Error Handling

The starter includes centralized error handling.

Relevant files:

src/middlewares/global-error-handler.ts
src/middlewares/not-found-middleware.ts
src/utils/ApiError.ts
src/utils/ApiResponse.ts
src/utils/async-handler.ts

Requirements

Before using the generated project, make sure you have:

• Node.js 18+
• pnpm
• PostgreSQL
• Redis if using Redis-related functionality

Generator Structure

The generator itself is organized like this:

create-express-pg-api/
├── src/
│   └── cli.ts
├── template/
├── dist/
├── package.json
├── README.md
└── tsconfig.json

src/cli.ts

Contains the CLI logic used to:

• Read the project name
• Create the destination directory
• Copy the backend template
• Update the generated project's package name
• Create .gitignore
• Install dependencies

template/

Contains the backend starter that is copied whenever someone runs:

pnpm create express-pg-api my-project

Updating the Package

The package follows semantic versioning.

2.0.1 → bug fixes or documentation updates
2.1.0 → new backward-compatible features
3.0.0 → breaking changes

For example, after making a small fix:

npm version patch
npm publish

npm Package

Package name:

create-express-pg-api

Create a project with:

pnpm create express-pg-api my-project

License

ISC