Skip to content

Latest commit

 

History

History
157 lines (120 loc) · 5.42 KB

README.md

File metadata and controls

157 lines (120 loc) · 5.42 KB

Disclaimer: This README.md file was generated by an LLM (Large Language Model).

Pragmatic Node.js API

A pragmatic foundation for building maintainable REST APIs with Node.js, Express, and TypeScript, using Vertical Slice Architecture.

✨ Features

  • Vertical Slice Architecture: Each feature is self-contained with its own endpoints, services, DTOs, mappers, and validation schemas.
  • Domain Logic: Rich domain entities with factory methods and business invariants.
  • Schema Validation: Request validation powered by Zod, with structured error responses.
  • Global Error Handling: Centralized exception handling middleware for consistent API error responses.
  • TypeScript by Default: Enjoy the benefits of static typing for more robust and maintainable code.
  • Configuration Management: Type-safe, centralized environment variable management with dotenv.
  • Developer-Friendly: Hot-reloading with tsx for a smooth development experience.
  • Linter & Formatter: Integrated with BiomeJS for clean and consistent code.
  • Ready to Deploy: Includes scripts for building and starting a production-ready server.

🏁 Getting Started

Prerequisites

Installation

  1. Clone the repository:

    git clone https://github.com/poschuler/pragmatic-nodejs-api.git

  2. Navigate to the project directory:

    cd pragmatic-nodejs-api

  3. Install the dependencies:

    npm install

  4. Create a .env file from the template:

    cp .env.template .env

Running the Application

  • Development Mode: To start the server in development mode with hot-reloading, run:

    npm run dev

    The server will be available at http://localhost:3000.

  • Production Mode: To build and start the application in production mode, run:

    npm run start

📡 API Endpoints

Method Path Description
GET /health Health check
GET /api/products List all products
POST /api/products Create a new product

Example: Create a Product

curl -X POST http://localhost:3000/api/products \
  -H "Content-Type: application/json" \
  -d '{"name": "Product 1", "description": "Description of Product 1", "price": 9.99}'

📜 Available Scripts

  • npm run dev: Starts the application in development mode with hot-reloading.
  • npm run build: Compiles the TypeScript code to JavaScript in the dist directory.
  • npm run start: Builds and starts the production version of the application.
  • npm run biome:lint: Lints the codebase for errors.
  • npm run biome:lint:fix: Lints and fixes the codebase.
  • npm run biome:format: Formats the codebase.
  • npm run biome:format:fix: Formats and writes the changes to the codebase.

🏗️ Project Structure

The project follows a vertical-slice, feature-oriented directory structure.

src/
├── app.ts                          # Main application entry point
├── server.ts                       # Core Server class (Express wrapper)
├── routes.ts                       # Main application router & middleware composition
│
├── config/
│   └── config.ts                   # Environment variable management
│
├── domain/
│   └── product.entity.ts           # Product domain entity with factory method
│
├── exceptions/
│   ├── validation-error.ts         # ValidationError interface
│   └── validation-exception.ts     # ValidationException class
│
├── middlewares/
│   └── exception-handler.middleware.ts  # Global error handling middleware
│
├── shared/
│   └── validations/
│       └── validate-request-with-schema.ts  # Zod schema validation utility
│
└── features/
    └── products/                   # Products feature module
        ├── products.routes.ts      # Products router factory
        ├── products.service.ts     # Products business logic service
        │
        ├── create-product/         # Create Product endpoint (vertical slice)
        │   ├── create-product.endpoint.ts
        │   ├── create-product.mapper.ts
        │   ├── create-product.request.ts
        │   ├── create-product.response.ts
        │   └── create-products.schema.ts
        │
        └── get-products/           # Get Products endpoint (vertical slice)
            ├── get-products.endpoint.ts
            ├── get-products.mapper.ts
            └── get-products.response.ts

🛠️ Technology Stack

🤝 Contributing

Contributions are welcome! Please read our AGENTS.md for guidelines on how to collaborate with the project, especially when using AI agents.

📄 License

This project is licensed under the MIT License. See the LICENSE file for details.