mirror of
https://github.com/johndoe6345789/postgres.git
synced 2026-04-27 15:24:59 +00:00
0902346a7f
- Fixed PostgreSQL database creation error by using ALTER DATABASE instead of createdb - Rewrote README.md to be project-specific instead of generic boilerplate - Created comprehensive ROADMAP.md with short, medium, and long-term plans - Verified unit tests are working (7 tests passing) Co-authored-by: johndoe6345789 <224850594+johndoe6345789@users.noreply.github.com>
247 lines
6.7 KiB
Markdown
247 lines
6.7 KiB
Markdown
# 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:
|
|
```bash
|
|
git clone https://github.com/johndoe6345789/postgres.git
|
|
cd postgres
|
|
```
|
|
|
|
2. Install dependencies:
|
|
```bash
|
|
npm install
|
|
```
|
|
|
|
3. Set up environment variables:
|
|
Create a `.env.local` file:
|
|
```env
|
|
# 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:
|
|
```bash
|
|
npm run dev
|
|
```
|
|
|
|
5. Open http://localhost:3000 in your browser.
|
|
|
|
### Docker Deployment
|
|
|
|
Build and run the application with Docker:
|
|
|
|
```bash
|
|
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](https://clerk.com) for authentication. To set up:
|
|
|
|
1. Create a Clerk account and application
|
|
2. Copy your API keys to `.env.local`:
|
|
```env
|
|
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:
|
|
```bash
|
|
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:
|
|
```bash
|
|
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:
|
|
```bash
|
|
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:
|
|
|
|
```bash
|
|
# 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](https://www.conventionalcommits.org/). Use the interactive commit tool:
|
|
|
|
```bash
|
|
npm run commit
|
|
```
|
|
|
|
## Roadmap
|
|
|
|
See [ROADMAP.md](ROADMAP.md) for planned features and improvements.
|
|
|
|
## License
|
|
|
|
Licensed under the MIT License. See [LICENSE](LICENSE) for more information.
|
|
|
|
## Support
|
|
|
|
For issues, questions, or contributions, please open an issue on the GitHub repository.
|