andwati/blog-nest
1
0
Fork 0
mirror of https://github.com/andwati/blog-nest.git synced 2026-10-18 05:32:53 +00:00
Code Issues Packages Projects Releases Wiki Activity

feat: update README.md with comprehensive tech stack, setup instructions, and development guidelines

Browse Source
This commit is contained in:
andwati
2026-03-06 19:37:55 +03:00
parent 5bb086c86a
commit 409b9454c0
2 changed files with 440 additions and 26 deletions
Download Patch File Download Diff File Expand all files Collapse all files
.github/.copilot-instructions.md
+54 -26
View File
@@ -22,19 +22,34 @@ Produce production-grade changes that are correct, verifiable, maintainable, and
- **Git Hooks**: Lefthook (lefthook.yml)
### Key Dependencies & Tools
- NestJS + Prisma (backend data access)
- Next.js 14+ with App Router
- Expo + Expo Router
- class-validator, class-transformer (DTOs)
- Biome for linting + formatting
- Jest for unit/integration tests
- TypeScript strict mode enabled
- **Backend (apps/api)**:
- NestJS 11.0.1
- Prisma ORM 7.4.2 with @prisma/client 7.4.2
- TypeScript 5.7.3
- Jest 30.0.0
- class-validator & class-transformer (DTOs)
- **Frontend (apps/frontend)**:
- Next.js 16.1.6 with App Router
- React 19.2.3
- Tailwind CSS 4
- Jest 30.2.0
- TypeScript 5
- **Mobile (apps/mobile)**:
- Expo 55.0.5 with Expo Router
- React Native 0.83.2
- React 19.2.0
- **Tooling**:
- Biome 2.4.6 (linting + formatting)
- Turbo 2.8.13 (monorepo orchestration)
- Lefthook 2.1.2 (git hooks)
- TypeScript strict mode enabled across all apps
### Runtime & Package Manager
- **Node.js**: 24.x (see `.nvmrc`)
- **Node.js**: v24.14.0 (see `.nvmrc` for version pinning)
- **Package Manager**: pnpm@10.30.3
- **Commands**: `pnpm dev`, `pnpm test`, `pnpm lint`, `pnpm build`
- **Monorepo Command**: `pnpm --filter <workspace-name> <task>`
- Workspace names: `api`, `frontend`, `mobile`
- **Turbo Commands**: `turbo run <task>` (respects pnpm workspaces)
### Production Deployment
@@ -78,10 +93,10 @@ A task is complete only when all applicable items pass:
1. ✓ Requested behavior implemented.
2. ✓ All touched files are lint/error clean (run `pnpm lint` or `pnpm --filter <app> run biome check --write`).
3. ✓ Tests relevant to the change pass:
- Backend: `pnpm --filter @dpep/api test` (or targeted test file)
- Backend: `pnpm --filter api test` (or targeted test file)
- Frontend: `pnpm --filter frontend test` (if test harness exists)
- Mobile: `pnpm --filter mobile test` (if test harness exists)
4. ✓ Coverage for touched backend files is at least 90% when running `pnpm --filter @dpep/api run test:cov`.
4. ✓ Coverage for touched backend files is at least 90% when running `pnpm --filter api run test:cov`.
5. ✓ No duplicated logic introduced when a reusable abstraction is appropriate.
6. ✓ Public API changes include all call-site and type updates across apps.
7. ✓ Final diff is minimal and free of unrelated edits.
@@ -103,13 +118,13 @@ A task is complete only when all applicable items pass:
```
5. If Prisma schema changes (backend only):
```bash
pnpm --filter @dpep/api run prisma migrate dev --name <migration-name>
pnpm --filter @dpep/api run prisma generate
pnpm --filter api run prisma:migrate:dev --name <migration-name>
pnpm --filter api run prisma:generate
```
6. Run focused tests for changed behavior:
```bash
# Backend
pnpm --filter @dpep/api test -- <file-pattern>
pnpm --filter api test -- <file-pattern>
# Frontend
pnpm --filter frontend test -- <file-pattern>
@@ -121,7 +136,7 @@ A task is complete only when all applicable items pass:
### Verification
7. Run coverage checks when available (backend):
```bash
pnpm --filter @dpep/api run test:cov
pnpm --filter api run test:cov
```
- Refactor if quality gates fail (aim for ≥90% coverage on touched files).
8. Finalize only after all gates pass.
@@ -138,10 +153,11 @@ A task is complete only when all applicable items pass:
## 6. Code Purity and Output Rules
- Generate raw executable code only.
- **Forbidden**: commented-out code, inline rationale comments, placeholder comments.
- **Forbidden**: commented-out code, inline rationale comments, placeholder comments, emojis.
- **Allowed**: required JSDoc/docstrings explaining non-obvious logic.
- Keep code deterministic, explicit, and readable.
- Follow Biome's auto-formatting output; do not argue style choices.
- Never use emojis in code, documentation, commit messages, or any project files.
---
@@ -157,11 +173,17 @@ A task is complete only when all applicable items pass:
### 7.2 Prisma and Data Access
- Use Prisma client for data access; avoid raw SQL unless strictly necessary.
- **Prisma v7 Configuration**:
- Connection URL configured in `apps/api/prisma.config.ts` (NOT in schema file)
- Config file loads root `.env` from `../../.env`
- Schema location: `apps/api/prisma/schema.prisma`
- Migrations: `apps/api/prisma/migrations/`
- Use Prisma Client for data access; avoid raw SQL unless strictly necessary.
- Model relations in Prisma schema, not as loose id fields.
- Use transactions for multi-step writes.
- Avoid N+1 queries: use `include`/`select` and batching.
- Keep Prisma schema well-organized by model.
- Always use workspace scripts: `prisma:generate`, `prisma:migrate:dev`, `prisma:studio`
### 7.3 Auth, Cache, and Integrations
@@ -171,9 +193,10 @@ A task is complete only when all applicable items pass:
### 7.4 Migrations
- Always generate migrations via `prisma migrate dev --name <name>`.
- Never hand-edit migration files.
- Commit both schema and migration files.
- Always generate migrations via `pnpm --filter api run prisma:migrate:dev --name <name>`.
- Never hand-edit migration files unless absolutely necessary for data migration.
- Commit schema, config, and migration files together.
- For production: use `pnpm --filter api run prisma:migrate:deploy`.
### 7.5 Error Handling
@@ -285,11 +308,11 @@ import { MyService } from './my.service';
### 12.1 Baseline Requirements
- **Backend changes**: run targeted `pnpm --filter @dpep/api test <pattern>` or E2E tests if relevant.
- **Backend changes**: run targeted `pnpm --filter api test <pattern>` or E2E tests if relevant.
- **Frontend changes**: run relevant tests if a harness exists (`pnpm --filter frontend test`).
- **Mobile changes**: run relevant tests if a harness exists (`pnpm --filter mobile test`).
- **All changes**: always run Biome lint checks on touched files and pass all formatting.
- **Backend logic changes**: run `pnpm --filter @dpep/api run test:cov` to verify coverage ≥90%.
- **Backend logic changes**: run `pnpm --filter api run test:cov` to verify coverage ≥90%.
### 12.2 Required Test Scenarios by Change Type
@@ -374,10 +397,11 @@ pnpm dev # Start dev servers (Turbo orchestrated)
### Workspace-Specific
```bash
# Backend (apps/api)
pnpm --filter @dpep/api test
pnpm --filter @dpep/api run test:cov
pnpm --filter @dpep/api run prisma migrate dev --name <name>
pnpm --filter @dpep/api run prisma studio
pnpm --filter api test
pnpm --filter api run test:cov
pnpm --filter api run prisma:migrate:dev --name <name>
pnpm --filter api run prisma:studio
pnpm --filter api run prisma:generate
# Frontend (apps/frontend)
pnpm --filter frontend dev
@@ -411,7 +435,11 @@ pnpm dev
# Check Turbo cache
turbo --version
turbo prune --docker --scope=@dpep/api # For monorepo analysis
turbo prune --docker --scope=api # For monorepo analysis
# Prisma-specific troubleshooting
pnpm --filter api run prisma:generate # Regenerate client
pnpm --filter api exec prisma validate --config prisma.config.ts # Validate schema
```
---
README.md
+386
View File
@@ -0,0 +1,386 @@
# Blog Nest
A modern full-stack blog platform built with TypeScript, featuring a NestJS backend API, Next.js web frontend, and Expo mobile app.
## Tech Stack
### Backend (API)
- **NestJS** 11.0.1 - Progressive Node.js framework
- **Prisma ORM** 7.4.2 - Type-safe database access
- **PostgreSQL** 17 - Primary database
- **Redis** 7 - Caching layer
- **TypeScript** 5.7.3 - Static typing
- **Jest** 30.0.0 - Testing framework
### Frontend (Web)
- **Next.js** 16.1.6 - React framework with App Router
- **React** 19.2.3 - UI library
- **Tailwind CSS** 4 - Utility-first CSS
- **TypeScript** 5 - Static typing
- **Jest** 30.2.0 - Testing framework
### Mobile (App)
- **Expo** 55.0.5 - React Native framework
- **Expo Router** - File-based routing
- **React Native** 0.83.2 - Mobile framework
- **React** 19.2.0 - UI library
- **TypeScript** - Static typing
### Tooling
- **Turbo** 2.8.13 - Monorepo orchestration
- **pnpm** 10.30.3 - Package manager
- **Biome** 2.4.6 - Linting & formatting
- **Lefthook** 2.1.2 - Git hooks
- **Docker** - Containerization
- **Nginx** - Reverse proxy (production)
## Prerequisites
- **Node.js** v24.14.0 (use `.nvmrc` for version management)
- **pnpm** 10.30.3 or higher
- **Docker** & Docker Compose
- **Git**
## Quick Start
### 1. Clone the repository
```bash
git clone <repository-url>
cd blog-nest
```
### 2. Install dependencies
```bash
pnpm install
```
### 3. Set up environment variables
```bash
cp .env.example .env
# Edit .env with your configuration
```
### 4. Start development database
```bash
pnpm docker:dev
```
### 5. Run database migrations
```bash
pnpm --filter api run prisma:migrate:dev
```
### 6. Start development servers
```bash
pnpm dev
```
This starts all apps in parallel:
- **API**: http://localhost:3001
- **Frontend**: http://localhost:3000
- **Mobile**: Expo DevTools (follow terminal instructions)
## Project Structure
```
blog-nest/
├── apps/
│ ├── api/ # NestJS backend API
│ │ ├── prisma/ # Prisma schema & migrations
│ │ ├── src/ # Source code
│ │ └── test/ # E2E tests
│ ├── frontend/ # Next.js web application
│ │ └── src/ # Source code
│ └── mobile/ # Expo mobile application
│ ├── assets/ # Static assets
│ └── src/ # Source code
├── infra/ # Infrastructure configuration
│ ├── docker-compose.yml
│ └── nginx.conf
├── .github/ # GitHub configuration
├── package.json # Root package.json
├── pnpm-workspace.yaml # pnpm workspace config
├── turbo.json # Turbo configuration
├── biome.json # Biome linting config
└── lefthook.yml # Git hooks configuration
```
## Development
### Available Commands
#### Root Level (affects all apps)
```bash
pnpm dev # Start all apps in development mode
pnpm build # Build all apps
pnpm test # Run tests in all apps
pnpm lint # Lint all apps
pnpm clean # Clean build artifacts
pnpm check-types # Type-check all apps
```
#### Workspace-Specific Commands
**Backend (API)**
```bash
pnpm --filter api dev # Start dev server
pnpm --filter api build # Build for production
pnpm --filter api test # Run unit tests
pnpm --filter api run test:cov # Run tests with coverage
pnpm --filter api run test:e2e # Run E2E tests
pnpm --filter api run prisma:generate # Generate Prisma Client
pnpm --filter api run prisma:migrate:dev # Run migrations (dev)
pnpm --filter api run prisma:migrate:deploy # Run migrations (prod)
pnpm --filter api run prisma:studio # Open Prisma Studio
```
**Frontend (Web)**
```bash
pnpm --filter frontend dev # Start dev server
pnpm --filter frontend build # Build for production
pnpm --filter frontend start # Start production server
pnpm --filter frontend test # Run tests
pnpm --filter frontend lint # Lint code
```
**Mobile (App)**
```bash
pnpm --filter mobile dev # Start Expo DevTools
pnpm --filter mobile android # Run on Android
pnpm --filter mobile ios # Run on iOS
pnpm --filter mobile web # Run on web
pnpm --filter mobile test # Run tests
```
### Docker Commands
```bash
# Development
pnpm docker:dev # Start PostgreSQL & Redis
pnpm docker:down # Stop all containers
# Production
pnpm docker:prod # Start all services (production)
pnpm docker:prod:down # Stop production containers
```
## Database Management
### Prisma Workflow
1. **Update schema**: Edit `apps/api/prisma/schema.prisma`
2. **Create migration**:
```bash
pnpm --filter api run prisma:migrate:dev --name <migration_name>
```
3. **Apply to production**:
```bash
pnpm --filter api run prisma:migrate:deploy
```
4. **Explore data**:
```bash
pnpm --filter api run prisma:studio
```
### Configuration
Prisma v7 uses `apps/api/prisma.config.ts` for configuration:
- Connection URL loaded from root `.env` file
- Schema location: `apps/api/prisma/schema.prisma`
- Migrations stored in: `apps/api/prisma/migrations/`
## Testing
### Running Tests
```bash
# All apps
pnpm test
# Specific app
pnpm --filter api test
pnpm --filter frontend test
pnpm --filter mobile test
# With coverage
pnpm --filter api run test:cov
# Watch mode
pnpm --filter api run test:watch
```
### Test Structure
- **Unit tests**: `*.spec.ts` or `*.spec.tsx`
- **E2E tests**: `test/*.e2e-spec.ts` (backend only)
- **Coverage target**: ≥90% for backend code
## Configuration
### Environment Variables
Create a `.env` file in the project root:
```env
# Database
DATABASE_URL=postgresql://blog:postgres@localhost:5432/blog_dev
DATABASE_HOST=localhost
DATABASE_PORT=5432
DATABASE_NAME=blog_dev
DATABASE_USER=blog
DATABASE_PASSWORD=postgres
# API
API_PORT=3001
# Frontend
NEXT_PUBLIC_API_URL=http://localhost:3001
# Mobile
EXPO_PUBLIC_API_URL=http://localhost:3001
```
## Deployment
### Production Deployment
See [DEPLOY_VPS.md](DEPLOY_VPS.md) for complete VPS deployment guide including:
- Docker Compose setup
- Nginx reverse proxy configuration
- SSL/TLS with Let's Encrypt
- Database backup strategies
- Monitoring setup
### Quick Production Build
```bash
# Build all apps
pnpm build
# Start production services
pnpm docker:prod
```
## Code Quality
### Linting & Formatting
This project uses **Biome** for linting and formatting:
```bash
# Lint all code
pnpm lint
# Auto-fix issues
pnpm lint --write
# Check specific app
pnpm --filter api lint
```
### Git Hooks
**Lefthook** runs pre-commit checks:
- Linting staged files
- Type checking
- Running relevant tests
Hooks are automatically installed when you run `pnpm install`.
## Architecture Decisions
### Monorepo Strategy
- **Tool**: Turbo + pnpm workspaces
- **Benefits**: Shared TypeScript configs, parallel task execution, efficient caching
- **Workspace isolation**: Each app has its own dependencies and configuration
### Prisma v7
- Configuration moved from schema to `prisma.config.ts`
- Environment variables loaded from root `.env`
- Improved TypeScript integration and migration workflows
### Next.js App Router
- Server Components by default
- Client Components only when needed
- Optimized for performance and SEO
### Expo Router
- File-based routing for mobile app
- Seamless navigation between screens
- Web compatibility built-in
## Contributing
1. Create a feature branch: `git checkout -b feature/amazing-feature`
2. Make your changes
3. Run quality checks: `pnpm lint && pnpm test`
4. Commit following [Conventional Commits](https://www.conventionalcommits.org/):
```
feat(api): add user authentication
fix(frontend): resolve navigation bug
```
5. Push and create a Pull Request
### Commit Format
```
<type>(<scope>): <description>
[optional body]
[optional footer]
```
**Types**: `feat`, `fix`, `refactor`, `test`, `chore`, `perf`, `docs`
## Additional Documentation
- [API Documentation](apps/api/README.md)
- [Frontend Documentation](apps/frontend/README.md)
- [Mobile Documentation](apps/mobile/README.md)
- [Infrastructure Guide](infra/README.md)
- [Deployment Guide](DEPLOY_VPS.md)
- [Copilot Instructions](.github/.copilot-instructions.md)
## Troubleshooting
### Common Issues
**Port already in use**
```bash
# Kill processes on specific ports
pkill -f "next dev"
pkill -f "nest start"
```
**Stale dependencies**
```bash
pnpm clean
rm -rf node_modules
pnpm install
```
**Database connection issues**
```bash
# Restart database container
pnpm docker:down
pnpm docker:dev
```
**Prisma Client out of sync**
```bash
pnpm --filter api run prisma:generate
```
## License
[License Type] - See LICENSE file for details
## Team
- [Your Name/Team]
- [Contact Information]
---
Built with TypeScript