postgres/README.md

Next.js Application with PostgreSQL

A production-ready Next.js 16 application with integrated PostgreSQL database, built with TypeScript, Tailwind CSS, and modern development tools.

Overview

This project is a full-stack web application featuring:

• Next.js 16 with App Router for server-side rendering and static site generation
• PostgreSQL 15 database with DrizzleORM for type-safe database operations
• Authentication using Clerk with support for multiple auth providers
• TypeScript for type safety across the entire stack
• Tailwind CSS 4 for modern, responsive styling
• Docker support for easy deployment
• Comprehensive testing with Vitest, Playwright, and Storybook

Features

• ⚡ Next.js 16 with App Router support
• 🔥 TypeScript for type safety
• 💎 Tailwind CSS 4 for styling
• 🔒 Clerk Authentication with social login support
• 📦 DrizzleORM with PostgreSQL database
• 🐳 Docker support with all-in-one container
• 🧪 Testing Suite - Vitest for unit tests, Playwright for E2E
• 🎨 Storybook for UI component development
• 📏 ESLint & Prettier for code quality
• 🔍 TypeScript strict mode
• 🌐 Multi-language (i18n) support with next-intl
• 🚨 Error Monitoring with Sentry
• 🔐 Security with Arcjet (bot detection, rate limiting)

Quick Start

Prerequisites

• Node.js 20+ and npm
• Docker (optional, for containerized deployment)

Local Development

1. Clone the repository:

git clone https://github.com/johndoe6345789/postgres.git
cd postgres

2. Install dependencies:

npm install

3. Set up environment variables: Create a .env.local file:

# Database
DATABASE_URL=postgresql://docker:docker@localhost:5432/postgres

# Clerk Authentication
NEXT_PUBLIC_CLERK_PUBLISHABLE_KEY=your_key
CLERK_SECRET_KEY=your_secret

# Optional: Admin user creation
CREATE_ADMIN_USER=true
ADMIN_USERNAME=admin
ADMIN_PASSWORD=admin123

4. Run the development server:

npm run dev

5. Open http://localhost:3000 in your browser.

Docker Deployment

Build and run the application with Docker:

docker build -t postgres-app .
docker run -p 3000:3000 -p 5432:5432 \
  -e JWT_SECRET=your_secret_here \
  postgres-app

The Docker container includes both PostgreSQL and the Next.js application in a single image.

Project Structure

├── src/
│   ├── app/              # Next.js App Router pages
│   ├── components/       # React components
│   ├── models/           # Database models (DrizzleORM schemas)
│   ├── utils/            # Utility functions
│   ├── libs/             # Third-party library configurations
│   └── locales/          # i18n translations
├── tests/
│   ├── integration/      # Integration tests
│   └── e2e/              # End-to-end tests
├── migrations/           # Database migrations
├── public/               # Static assets
├── Dockerfile            # Docker configuration
└── docker-compose.yml    # Docker Compose setup

Available Scripts

Development

• npm run dev - Start development server with live reload
• npm run build - Build production bundle
• npm run start - Start production server
• npm run build-local - Build with local database

Database

• npm run db:generate - Generate database migrations
• npm run db:migrate - Apply database migrations
• npm run db:studio - Open Drizzle Studio (database GUI)
• npm run db:seed-admin - Seed admin user

Testing

• npm run test - Run unit tests
• npm run test:e2e - Run end-to-end tests
• npm run storybook - Start Storybook for component development

Code Quality

• npm run lint - Run ESLint
• npm run lint:fix - Fix linting issues automatically
• npm run check:types - Type check with TypeScript
• npm run check:deps - Check for unused dependencies
• npm run check:i18n - Validate translations

Utilities

• npm run commit - Interactive commit message generator (Conventional Commits)
• npm run generate:password - Generate secure passwords

Database Schema

Database schemas are defined in src/models/Schema.ts using DrizzleORM. To modify the schema:

1. Edit src/models/Schema.ts
2. Generate migration: npm run db:generate
3. Apply migration: npm run db:migrate

Authentication

This project uses Clerk for authentication. To set up:

1. Create a Clerk account and application
2. Copy your API keys to .env.local:

NEXT_PUBLIC_CLERK_PUBLISHABLE_KEY=pk_...
CLERK_SECRET_KEY=sk_...

Features include:

• Email/password authentication
• Social login (Google, GitHub, etc.)
• Multi-factor authentication (MFA)
• User management dashboard

Testing

Unit Tests

Run unit tests with Vitest:

npm run test

Unit tests are located alongside source files with .test.ts or .test.tsx extensions.

E2E Tests

Run end-to-end tests with Playwright:

npx playwright install  # First time only
npm run test:e2e

E2E tests are in the tests/e2e directory with .e2e.ts extensions.

Component Development

Use Storybook for isolated component development:

npm run storybook

Deployment

Environment Variables

Required environment variables for production:

• DATABASE_URL - PostgreSQL connection string
• NEXT_PUBLIC_CLERK_PUBLISHABLE_KEY - Clerk public key
• CLERK_SECRET_KEY - Clerk secret key
• JWT_SECRET - Secret for JWT token signing
• NODE_ENV=production

Optional:

• CREATE_ADMIN_USER - Set to true to create admin user on startup
• ADMIN_USERNAME - Admin username (default: admin)
• ADMIN_PASSWORD - Admin password (default: admin123)

Docker

The application can be deployed using the included Dockerfile:

# Build image
docker build -t postgres-app .

# Run container
docker run -d \
  -p 3000:3000 \
  -e DATABASE_URL="postgresql://..." \
  -e CLERK_SECRET_KEY="sk_..." \
  -e NEXT_PUBLIC_CLERK_PUBLISHABLE_KEY="pk_..." \
  -e JWT_SECRET="your-secret" \
  postgres-app

Contributing

1. Fork the repository
2. Create a feature branch (git checkout -b feature/amazing-feature)
3. Commit your changes using conventional commits (npm run commit)
4. Push to the branch (git push origin feature/amazing-feature)
5. Open a Pull Request

Commit Convention

This project follows Conventional Commits. Use the interactive commit tool:

npm run commit

Roadmap

See ROADMAP.md for planned features and improvements.

License

Licensed under the MIT License. See LICENSE for more information.

Support

For issues, questions, or contributions, please open an issue on the GitHub repository.