dodycode/nodejs-typescript-boilerplate

README

TypeScript Hono Drizzle Zod API Boilerplate

This project is a boilerplate for building a NodeJS API using TypeScript, Hono, Drizzle ORM, and Zod, that implemented Repository Design Pattern.

Features

TypeScript: For type-safe JavaScript development
Hono: A lightweight and fast web framework
Drizzle ORM: TypeScript ORM for SQL databases
Zod: Runtime type checking and validation
PostgreSQL: As the database backend
Repository Pattern: For clean separation of data access logic
Generic Base Repository: Reduces code repetition for CRUD operations
Input Validation: Using Zod schemas and custom middleware
Docker: Easy PostgreSQL setup with Docker Compose
Prettier: For consistent code formatting
ESLint: For identifying and fixing code quality issues

Prerequisites

Node.js (v14 or later recommended)
Docker and Docker Compose
npm or yarn package manager

Project Structure

.
├── src/
│   ├── controllers/
|   |   ├── todoController.ts
│   │   └── your-controller
│   ├── db/
│   │   ├── db.ts
│   │   └── schema.ts
│   ├── middleware/
│   │   └── validator.ts
│   ├── models/
|   |   ├── todo.ts
│   │   └── your-entity-model
│   ├── repositories/
│   │   ├── baseRepository.ts
│   │   ├── todoRepository.ts
│   │   └── your-repository
│   ├── routes/
|   |   ├── todoRoutes.ts
│   │   └── your-routes
│   └── index.ts
├── drizzle/
│   └── your-database-migration-files
├── .env.example
├── .eslintrc.js
├── .gitignore
├── .prettierrc
├── docker-compose.yml
├── drizzle.config.ts
├── package.json
├── README.md
└── tsconfig.json

Getting Started

Clone the repository:

git clone https://github.com/dodycode/ts-hono-drizzle-zod-boilerplate.git
cd ts-hono-drizzle-zod-boilerplate

Install dependencies:
```
npm install
```
Set up the PostgreSQL database using Docker:
```
docker-compose up -d
```
Set up your environment variables:
- Copy .env.example to .env
- Update DATABASE_URL in .env:
```
DATABASE_URL=postgres://myuser:mypassword@localhost:5432/myapp
```
  Note: You can configure postgre user in docker-compose.yml
Create database migrations:
```
npm run generate
```
Run database migrations:
```
npm run migrate
```
Start the development server:
```
npm run dev
```

The server should now be running on http://localhost:3000.

Database Management

This project uses Drizzle ORM for database management. Here are the available scripts and when to use them:

npm run generate: Generate Drizzle migration files (run this after making changes to your schema)
npm run migrate: Run Drizzle migrations (use this for the initial setup and when you want to apply migrations)
npm run push: Push schema changes to the database (use this during development to quickly apply schema changes)
npm run studio: Open Drizzle Studio for database management

Workflow for Schema Changes

Make changes to your schema in /src/server/db/schema/
Run pnpm generate or npm run generate to create a new migration
Run pnpm push or npm run push to apply the changes to your development database

For production or when you need to keep track of migrations:

Make changes to your schema
Run pnpm generate or npm run generate
Run pnpm migrate or npm run migrate to apply the migrations

Remember to commit the generated migration files to your version control system.

API Endpoints

GET /api/todos: Retrieve all todos
GET /api/todos/:id: Retrieve a specific todo
POST /api/todos: Create a new todo
PUT /api/todos/:id: Update an existing todo
DELETE /api/todos/:id: Delete a todo

Scripts

npm start: Start the development server
npm run build: Compile TypeScript to JavaScript
npm run migrate: Run database migrations
npm run lint: Run ESLint to check for code quality issues
npm run format: Run Prettier to automatically format your code
npm run format:check: Check if your code is properly formatted without making changes

Docker Commands

Start the PostgreSQL container: docker-compose up -d
Stop the PostgreSQL container: docker-compose down
View container logs: docker-compose logs

Adding New Entities

Define the entity schema in src/db/schema.ts
Create a model file in src/models/ with Zod schemas and type definitions
Create a repository in src/repositories/ extending the BaseRepository
Create a controller in src/controllers/
Define routes in src/routes/
Update src/index.ts to include the new routes

Contributing

Contributions are welcome! Please feel free to submit a Pull Request.