VPA API

A modern Node.js API built with Prisma, TypeGraphQL, Express, and TypeScript.

Features

• 🚀 Express.js - Fast, unopinionated web framework
• 🗄️ Prisma - Next-generation ORM with type safety
• 🐘 PostgreSQL - Robust, open-source relational database
• 📊 TypeGraphQL - GraphQL API with TypeScript decorators
• 🔌 Apollo Server - Production-ready GraphQL server
• 📡 GraphQL Subscriptions - Real-time updates with WebSockets
• 🔧 TypeScript - Type-safe development experience
• 🎨 Prettier & ESLint - Code formatting and linting
• 🧪 Jest - Testing framework
• 🔒 Envalid - Environment variable validation
• 🆕 Node 22 - Latest LTS Node.js features

Prerequisites

• Node.js >= 22.0.0
• PostgreSQL >= 12.0
• npm or yarn

Installation

1. Clone the repository:

git clone <your-repo-url>
cd vpa-api

2. Install dependencies:

npm install

3. Set up environment variables:

cp .env.example .env
# Edit .env with your PostgreSQL configuration

4. Set up the database:

npm run db:generate
npm run db:push

Development

Start the development server:

npm run dev

The API will be available at:

• GraphQL endpoint: http://localhost:4000/graphql
• GraphQL subscriptions: ws://localhost:4000/graphql

Available Scripts

• npm run dev - Start development server with hot reload
• npm run build - Build the project for production
• npm run start - Start production server
• npm run test - Run tests
• npm run lint - Run ESLint
• npm run format - Format code with Prettier
• npm run db:generate - Generate Prisma client
• npm run db:push - Push schema changes to database
• npm run db:migrate - Run database migrations
• npm run db:deploy - Deploy migrations to production
• npm run db:reset - Reset database (development only)
• npm run db:studio - Open Prisma Studio
• npm run db:seed - Run database seeders
• npm run clean - Clean build artifacts

Project Structure

src/
├── modules/          # Feature modules
│   └── user/        # User module with resolver
├── shared/           # Shared utilities and GraphQL setup
│   ├── env.config.ts # Environment configuration with validation
│   ├── graphql/     # GraphQL resolvers and schema
│   └── graphql-subscription/ # WebSocket subscriptions
└── app.ts           # Main application entry point

prisma/
├── schema.prisma    # Database schema
└── generated/       # Generated types (gitignored)
    └── type-graphql # TypeGraphQL generated types

Environment Configuration

This project uses Envalid for environment variable validation. The configuration is centralized in src/shared/env.config.ts and provides:

• Type-safe environment variables
• Runtime validation
• Default values
• Choice validation for specific variables
• SCREAM_SNAKE_CASE in .env files, camelCase in code

Environment Variables (.env file)

Server Configuration

• NODE_ENV - Environment (development/production/test)
• PORT - Server port (default: 4000)
• HOST - Server host (default: localhost)

PostgreSQL Configuration

• POSTGRES_USER - Database username (default: postgres)
• POSTGRES_PASSWORD - Database password (default: password)
• POSTGRES_HOST - Database host (default: localhost)
• POSTGRES_PORT - Database port (default: 5432)
• POSTGRES_DB - Database name (default: vpa_api)
• POSTGRES_SCHEMA - Database schema (default: public)
• DATABASE_URL - Full database connection string with variable substitution

GraphQL Configuration

• GRAPHQL_PATH - GraphQL endpoint path (default: /graphql)
• GRAPHQL_SUBSCRIPTIONS_PATH - WebSocket path (default: /graphql)

Other Configuration

• CORS_ORIGIN - CORS allowed origin (default: http://localhost:3000)
• LOG_LEVEL - Logging level (error/warn/info/debug)

Code Usage (camelCase)

In your application code, you can access these values using camelCase:

import { config } from './shared/env.config';

// Server configuration
const port = config.port; // 4000
const host = config.host; // 'localhost'

// PostgreSQL configuration
const dbUser = config.postgresUser; // 'postgres'
const dbName = config.postgresDb; // 'vpa_api'
const dbUrl = config.databaseUrl; // Full connection string

// GraphQL configuration
const gqlPath = config.graphqlPath; // '/graphql'

Database URL Configuration

The DATABASE_URL in your .env file uses environment variable substitution for a clean, maintainable configuration:

DATABASE_URL=postgresql://${POSTGRES_USER}:${POSTGRES_PASSWORD}@${POSTGRES_HOST}:${POSTGRES_PORT}/${POSTGRES_DB}?schema=${POSTGRES_SCHEMA}

This approach:

• ✅ Keeps all database configuration in one place
• ✅ Uses standard environment variable substitution
• ✅ Makes it easy to update individual components
• ✅ Maintains consistency across different environments

Database Setup

PostgreSQL Requirements

• Version: PostgreSQL 12.0 or higher
• Extensions: No special extensions required
• Permissions: User must have CREATE, ALTER, DROP privileges on the database

Initial Setup

1. Create a PostgreSQL database:

CREATE DATABASE vpa_api;

2. Update your .env file with database credentials:

POSTGRES_USER=your_username
POSTGRES_PASSWORD=your_password
POSTGRES_HOST=localhost
POSTGRES_PORT=5432
POSTGRES_DB=vpa_api
POSTGRES_SCHEMA=public
DATABASE_URL=postgresql://${POSTGRES_USER}:${POSTGRES_PASSWORD}@${POSTGRES_HOST}:${POSTGRES_PORT}/${POSTGRES_DB}?schema=${POSTGRES_SCHEMA}

3. Generate Prisma client and push schema:

npm run db:generate
npm run db:push

Migrations

For production deployments, use migrations:

npm run db:migrate    # Create and apply migration
npm run db:deploy     # Deploy existing migrations

GraphQL Schema

The API automatically generates a GraphQL schema from your Prisma models and TypeGraphQL resolvers. You can explore the schema using Apollo Studio at the GraphQL endpoint.

Adding New Modules

1. Create a new directory in src/modules/
2. Add your resolver with TypeGraphQL decorators
3. Export it from the module's index.ts
4. Add it to the resolvers array in src/shared/graphql/index.ts

Node 22 Compatibility

This project is optimized for Node.js 22+ and includes:

• Modern ES2022 TypeScript target
• Latest dependency versions
• Optimized build configuration
• Enhanced type safety

Contributing

1. Fork the repository
2. Create a feature branch
3. Make your changes
4. Run tests and linting
5. Submit a pull request

License

MIT