# Blitz.js + PostgreSQL

> Full-stack React framework inspired by Ruby on Rails.

- Category: Full Web Stacks
- Difficulty: intermediate
- Components: blitz, postgres
- Tags: blitz, react, postgres, prisma
- Source: https://docker.recipes/full-stacks/blitz-postgres

## Overview

Blitz.js is a full-stack React framework that emerged in 2020, inspired by Ruby on Rails' philosophy of convention over configuration. Created to eliminate the complexity of modern React development, Blitz.js provides a batteries-included approach with built-in authentication, database integration via Prisma ORM, and a revolutionary 'Zero-API' data layer that allows direct server function calls from client components without traditional REST or GraphQL APIs. The framework emphasizes rapid development through code generation, automatic TypeScript support, and opinionated project structure that reduces decision fatigue.

This stack pairs Blitz.js with PostgreSQL to create a robust full-stack development environment where PostgreSQL's ACID compliance and advanced querying capabilities complement Blitz.js's type-safe database operations through Prisma. PostgreSQL's mature transaction handling ensures data integrity for Blitz.js applications, while its JSON/JSONB support provides flexibility for storing complex application state alongside traditional relational data. The combination leverages PostgreSQL's full-text search capabilities for content-heavy applications and its extensible nature for custom business logic requirements.

This configuration targets developers building modern web applications who want Rails-like productivity with React's ecosystem benefits. Startups requiring rapid MVP development, teams transitioning from monolithic frameworks to modern JavaScript stacks, and developers building customer-facing applications with complex data relationships will find this stack particularly valuable. The combination eliminates the typical complexity of setting up authentication, database migrations, and API layers while maintaining the scalability and performance characteristics needed for production applications.

## Features

- Zero-API data layer enabling direct server function calls from React components without REST endpoints
- Built-in Prisma ORM integration with PostgreSQL for type-safe database operations and automatic migrations
- Blitz Auth system with session-based authentication, password hashing, and user management out of the box
- Rails-inspired code generators (blitz generate all) for rapid scaffolding of models, queries, and mutations
- PostgreSQL's JSONB support for storing complex application state alongside relational data with full indexing
- Full-text search capabilities using PostgreSQL's built-in search features with ranking and highlighting
- Automatic TypeScript configuration with end-to-end type safety from database to frontend components
- Hot reloading development environment with automatic database schema synchronization

## Use cases

- SaaS applications requiring user authentication, subscription management, and complex data relationships
- E-commerce platforms needing product catalogs, inventory management, and order processing with ACID transactions
- Content management systems leveraging PostgreSQL's full-text search for articles, documentation, or blogs
- Customer relationship management (CRM) tools with complex queries across related entities like contacts, deals, and activities
- Multi-tenant applications using PostgreSQL's row-level security and schema isolation features
- Analytics dashboards requiring complex aggregations and window functions across large datasets
- Social platforms needing user profiles, relationships, and activity feeds with real-time updates

## Prerequisites

- Docker and Docker Compose installed with minimum 2GB RAM available for PostgreSQL operations
- Node.js 16+ knowledge and familiarity with React hooks and component patterns
- Basic understanding of SQL queries and relational database concepts for Prisma schema design
- Environment file (.env) configured with DB_NAME, DB_USER, and DB_PASSWORD variables
- Port 3000 available for Blitz.js development server and port 5432 for PostgreSQL connections
- Dockerfile present in project root for Blitz.js application build process

## docker-compose.yml

```yaml
services:
  blitz:
    build: .
    container_name: blitz
    environment:
      DATABASE_URL: postgresql://${DB_USER}:${DB_PASSWORD}@postgres:5432/${DB_NAME}
    ports:
      - "3000:3000"
    depends_on:
      - postgres
    networks:
      - blitz-network

  postgres:
    image: postgres:16-alpine
    environment:
      POSTGRES_DB: ${DB_NAME}
      POSTGRES_USER: ${DB_USER}
      POSTGRES_PASSWORD: ${DB_PASSWORD}
    volumes:
      - postgres_data:/var/lib/postgresql/data
    networks:
      - blitz-network

volumes:
  postgres_data:

networks:
  blitz-network:
    driver: bridge
```

## .env

```bash
DB_NAME=blitz
DB_USER=blitz
DB_PASSWORD=changeme
```

## Usage notes

- Docs: https://blitzjs.com/docs
- Access at http://localhost:3000
- Zero-API: call server functions directly from components
- Built-in authentication with blitz auth
- Prisma ORM included
- Rails-like generators: blitz generate all

## Troubleshooting

- Prisma client generation errors: Run 'blitz prisma generate' after schema changes and rebuild the container
- Database connection refused: Ensure postgres service is fully started before blitz container using depends_on healthcheck
- Migration failures on startup: Check DATABASE_URL format and verify PostgreSQL credentials match environment variables
- Blitz auth session issues: Verify SESSION_SECRET_KEY is set in environment and consistent across container restarts
- Port 3000 already in use: Stop existing Node.js processes or change the host port mapping in docker-compose.yml
- PostgreSQL data persistence lost: Ensure postgres_data volume is properly mounted to /var/lib/postgresql/data

