npm package: @hiqaody/create-backend-pg
Description: NestJS backend template with PostgreSQL and TypeORM
Author: Jacquinot
Latest version: 1.1.9

# @hiqaody/create-backend-pg

<div align="center">

[![npm version](https://img.shields.io/npm/v/@hiqaody/nestjs-backend-pg.svg)](https://www.npmjs.com/package/@hiqaody/nestjs-backend-pg)
[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)
[![Node.js Version](https://img.shields.io/badge/node-%3E%3D20.0.0-brightgreen)](https://nodejs.org)
[![NestJS](https://img.shields.io/badge/NestJS-Framework-red)](https://nestjs.com)
[![TypeScript](https://img.shields.io/badge/TypeScript-5.0+-blue)](https://www.typescriptlang.org/)
[![PostgreSQL](https://img.shields.io/badge/PostgreSQL-16+-316192)](https://www.postgresql.org/)

**🚀 Générateur de backend NestJS + PostgreSQL prêt pour la production**

*Créez une API REST complète avec authentification, base de données et bonnes pratiques en moins de 2 minutes*

[Démarrage Rapide](#-démarrage-rapide) • [Documentation](#-fonctionnalités) • [Exemples](#-exemples-dutilisation) • [Support](#-support)

</div>

---

## ✨ Pourquoi choisir ce template ?

- 🎯 **Configuration zéro** : PostgreSQL + TypeORM préconfigurés
- 🔒 **Sécurité intégrée** : Helmet, CORS, validation des données
- 📦 **Architecture modulaire** : Structure NestJS optimale
- 🧪 **Tests inclus** : Jest configuré pour tests unitaires et E2E
- 🐳 **Docker ready** : Déploiement conteneurisé simplifié
- ⚡ **TypeScript strict** : Typage fort et autocomplétion
- 🔄 **Hot reload** : Développement rapide avec watch mode
- 📝 **ESLint + Prettier** : Code formaté automatiquement

---

## 🚀 Démarrage Rapide

### Prérequis

- Node.js ≥ 20.0.0
- PostgreSQL ≥ 12
- npm ou yarn

### Installation

#### Option 1 : Mode interactif (Recommandé)
```bash
npx @hiqaody/create-backend-pg
```

#### Option 2 : Mode rapide
```bash
npx @hiqaody/create-backend-pg mon-api
cd mon-api
npm install
npm run start:dev
```

#### Option 3 : Avec npm create
```bash
npm create @hiqaody/backend-pg mon-api
```

### Configuration guidée

Le CLI vous accompagne étape par étape :

```bash
🎯 Bienvenue dans le générateur NestJS + PostgreSQL

📝 Configuration du projet
→ Nom du projet : mon-api
→ Description : Mon API REST

🗄️  Configuration PostgreSQL
→ Hôte : localhost
→ Port : 5432
→ Utilisateur : postgres
→ Mot de passe : ********
→ Base de données : mon_api_db

⚙️  Configuration application
→ Port : 3000
→ Environnement : development

✅ Projet créé avec succès !
```

---

## 📁 Architecture du Projet

```
mon-api/
├── 📂 src/
│   ├── 📂 config/                    # Configuration centralisée
│   │   ├── configuration.module.ts
│   │   └── env.validation.ts
│   ├── 📂 database/                  # Module base de données
│   │   ├── database.module.ts
│   │   ├── database.service.ts
│   │   └── migrations/
│   ├── 📂 common/                    # Utilitaires partagés
│   │   ├── decorators/
│   │   ├── filters/
│   │   ├── guards/
│   │   ├── interceptors/
│   │   └── pipes/
│   ├── 📂 health/                    # Module Health (nest g resource)
│   │   ├── health.controller.ts
│   │   ├── health.controller.spec.ts
│   │   ├── health.service.ts
│   │   ├── health.service.spec.ts
│   │   └── health.module.ts
│   ├── 📂 users/                     # Exemple module (nest g resource)
│   │   ├── 📂 dto/
│   │   │   ├── create-user.dto.ts
│   │   │   └── update-user.dto.ts
│   │   ├── 📂 entities/
│   │   │   └── user.entity.ts
│   │   ├── users.controller.ts
│   │   ├── users.controller.spec.ts
│   │   ├── users.service.ts
│   │   ├── users.service.spec.ts
│   │   └── users.module.ts
│   ├── app.module.ts                 # Module racine
│   ├── app.controller.ts
│   ├── app.service.ts
│   └── main.ts                       # Point d'entrée
├── 📂 test/
│   ├── app.e2e-spec.ts
│   ├── jest-e2e.json
│   └── setup.ts
├── 📂 docker/
│   ├── Dockerfile
│   ├── docker-compose.yml
│   └── .dockerignore
├── .env                              # Variables d'environnement
├── .env.example                      # Template de configuration
├── .gitignore
├── .prettierrc
├── eslint.config.mjs
├── nest-cli.json
├── package.json
├── tsconfig.json
├── tsconfig.build.json
└── README.md
```

---

## 🎯 Fonctionnalités

### 🏗️ Backend Complet

- **Framework NestJS** : Architecture modulaire et scalable
- **TypeORM** : ORM puissant avec migrations automatiques
- **PostgreSQL** : Base de données relationnelle robuste
- **Validation** : class-validator pour validation des DTOs
- **Configuration** : @nestjs/config avec validation de schéma
- **Logging** : Winston pour logs structurés

### 🔐 Sécurité

- **Helmet** : Protection des headers HTTP
- **CORS** : Configuration cross-origin sécurisée
- **Rate limiting** : Protection contre les attaques DDoS
- **Validation des entrées** : Sanitisation automatique
- **Variables d'environnement** : Gestion sécurisée des secrets
- **JWT prêt** : Secret généré automatiquement

### 🧪 Tests & Qualité

- **Jest** : Framework de test complet
- **Tests E2E** : Tests d'intégration configurés
- **Couverture de code** : Rapports détaillés
- **ESLint** : Linting avec règles NestJS
- **Prettier** : Formatage automatique du code
- **Husky** : Git hooks pour qualité du code

### 🐳 DevOps

- **Docker** : Configuration multi-stage optimisée
- **Docker Compose** : Orchestration locale
- **Health checks** : Endpoints de santé intégrés
- **CI/CD ready** : Templates GitHub Actions
- **Migrations** : Gestion des schémas de base de données

---

## 🛠️ Commandes Disponibles

### Développement

| Commande | Description |
|----------|-------------|
| `npm run start` | Démarre l'application |
| `npm run start:dev` | Mode développement avec hot-reload |
| `npm run start:debug` | Mode debug |
| `npm run start:prod` | Mode production |

### Build & Production

| Commande | Description |
|----------|-------------|
| `npm run build` | Compile le projet |
| `npm run format` | Formate le code avec Prettier |
| `npm run lint` | Vérifie le code avec ESLint |
| `npm run lint:fix` | Corrige automatiquement les erreurs |

### Tests

| Commande | Description |
|----------|-------------|
| `npm test` | Lance les tests unitaires |
| `npm run test:watch` | Tests en mode watch |
| `npm run test:cov` | Tests avec couverture |
| `npm run test:debug` | Tests en mode debug |
| `npm run test:e2e` | Tests end-to-end |

### Base de données

| Commande | Description |
|----------|-------------|
| `npm run typeorm migration:generate -- -n NomMigration` | Génère une migration |
| `npm run typeorm migration:run` | Exécute les migrations |
| `npm run typeorm migration:revert` | Annule la dernière migration |
| `npm run db:seed` | Peuple la base de données |
| `npm run db:reset` | Réinitialise la base |

---

## 🔧 Configuration

### Variables d'environnement

Le fichier `.env` est automatiquement généré avec des valeurs sécurisées :

```env
# Application
NODE_ENV=development
APP_PORT=3000
APP_HOST=localhost
APP_NAME=mon-api

# Database
POSTGRES_HOST=localhost
POSTGRES_PORT=5432
POSTGRES_USER=postgres
POSTGRES_PASSWORD=votre_mot_de_passe_secure
POSTGRES_DB=mon_api_db
POSTGRES_SSL=false
POSTGRES_SYNC=false

# JWT (généré automatiquement avec crypto.randomBytes)
JWT_SECRET=votre_secret_jwt_ultra_securise
JWT_EXPIRES_IN=1h

# Logging
LOG_LEVEL=debug

# CORS
CORS_ORIGIN=http://localhost:3001
```

### Configuration TypeORM

```typescript
// src/database/database.module.ts
TypeOrmModule.forRootAsync({
  imports: [ConfigModule],
  useFactory: (config: ConfigService) => ({
    type: 'postgres',
    host: config.get('POSTGRES_HOST'),
    port: config.get<number>('POSTGRES_PORT'),
    username: config.get('POSTGRES_USER'),
    password: config.get('POSTGRES_PASSWORD'),
    database: config.get('POSTGRES_DB'),
    entities: [__dirname + '/../**/*.entity{.ts,.js}'],
    migrations: [__dirname + '/migrations/**/*{.ts,.js}'],
    synchronize: config.get('NODE_ENV') === 'development',
    logging: config.get('NODE_ENV') === 'development',
  }),
  inject: [ConfigService],
})
```

---

## 💡 Exemples d'Utilisation

### Créer un module CRUD complet

```bash
# Générer un module avec tous les fichiers
nest g resource users

# Options proposées
? What transport layer do you use? REST API
? Would you like to generate CRUD entry points? Yes
```

**Résultat :**
```
src/users/
├── dto/
│   ├── create-user.dto.ts
│   └── update-user.dto.ts
├── entities/
│   └── user.entity.ts
├── users.controller.ts
├── users.controller.spec.ts
├── users.service.ts
├── users.service.spec.ts
└── users.module.ts
```

**Note importante :** Les modules générés avec `nest g resource` sont créés **directement à la racine de `src/`**, pas dans un sous-dossier `modules/`. C'est la convention standard recommandée par NestJS pour une meilleure organisation et découverte des modules.

### Créer une entité avec relations

```typescript
// src/users/entities/user.entity.ts
import { Entity, Column, PrimaryGeneratedColumn, CreateDateColumn, UpdateDateColumn, OneToMany } from 'typeorm';
import { Post } from '../../posts/entities/post.entity';

@Entity('users')
export class User {
  @PrimaryGeneratedColumn('uuid')
  id: string;

  @Column({ unique: true })
  email: string;

  @Column()
  password: string;

  @Column({ nullable: true })
  firstName: string;

  @Column({ nullable: true })
  lastName: string;

  @Column({ default: true })
  isActive: boolean;

  @OneToMany(() => Post, post => post.author)
  posts: Post[];

  @CreateDateColumn()
  createdAt: Date;

  @UpdateDateColumn()
  updatedAt: Date;
}
```

### Créer un DTO avec validation

```typescript
// src/users/dto/create-user.dto.ts
import { IsEmail, IsString, MinLength, MaxLength, IsOptional } from 'class-validator';

export class CreateUserDto {
  @IsEmail()
  email: string;

  @IsString()
  @MinLength(8)
  @MaxLength(100)
  password: string;

  @IsString()
  @IsOptional()
  @MaxLength(50)
  firstName?: string;

  @IsString()
  @IsOptional()
  @MaxLength(50)
  lastName?: string;
}
```

### Utiliser le service dans un controller

```typescript
// src/users/users.controller.ts
import { Controller, Get, Post, Body, Param, Delete, Put } from '@nestjs/common';
import { UsersService } from './users.service';
import { CreateUserDto } from './dto/create-user.dto';
import { UpdateUserDto } from './dto/update-user.dto';

@Controller('users')
export class UsersController {
  constructor(private readonly usersService: UsersService) {}

  @Post()
  create(@Body() createUserDto: CreateUserDto) {
    return this.usersService.create(createUserDto);
  }

  @Get()
  findAll() {
    return this.usersService.findAll();
  }

  @Get(':id')
  findOne(@Param('id') id: string) {
    return this.usersService.findOne(id);
  }

  @Put(':id')
  update(@Param('id') id: string, @Body() updateUserDto: UpdateUserDto) {
    return this.usersService.update(id, updateUserDto);
  }

  @Delete(':id')
  remove(@Param('id') id: string) {
    return this.usersService.remove(id);
  }
}
```

---

## 🐳 Déploiement Docker

### Développement local

```bash
# Démarrer tous les services
docker-compose up -d

# Voir les logs
docker-compose logs -f

# Arrêter les services
docker-compose down
```

### Production

```dockerfile
# Build optimisé
docker build -t mon-api:latest .

# Lancer le conteneur
docker run -p 3000:3000 --env-file .env mon-api:latest
```

---

## 🔍 Health Checks

Le template inclut des endpoints de santé :

```bash
# Vérifier l'état de l'application
curl http://localhost:3000/health

# Réponse
{
  "status": "ok",
  "info": {
    "database": { "status": "up" },
    "memory_heap": { "status": "up" },
    "memory_rss": { "status": "up" }
  }
}
```

---

## 🆘 Dépannage

### Erreur de connexion PostgreSQL

**Problème :** `Error: connect ECONNREFUSED`

**Solutions :**
```bash
# Vérifier que PostgreSQL est démarré
sudo systemctl status postgresql

# Ou avec Homebrew (macOS)
brew services list

# Ou avec Docker
docker ps | grep postgres

# Tester la connexion
psql -h localhost -U postgres -d mon_api_db
```

### Port déjà utilisé

**Problème :** `Error: listen EADDRINUSE: address already in use :::3000`

**Solution :**
```bash
# Trouver le processus qui utilise le port
lsof -i :3000

# Tuer le processus
kill -9 <PID>

# Ou changer le port dans .env
APP_PORT=3001
```

### Migrations échouées

**Problème :** Erreurs lors de l'exécution des migrations

**Solutions :**
```bash
# Réinitialiser la base de données
npm run db:reset

# Supprimer et recréer la base
dropdb mon_api_db && createdb mon_api_db

# Exécuter les migrations à nouveau
npm run typeorm migration:run
```

### Variables d'environnement manquantes

**Problème :** `Configuration validation error`

**Solution :**
```bash
# Copier le template
cp .env.example .env

# Éditer avec vos valeurs
nano .env
```

---

## 📚 Ressources

### Documentation officielle
- [NestJS Documentation](https://docs.nestjs.com)
- [TypeORM Documentation](https://typeorm.io)
- [PostgreSQL Documentation](https://www.postgresql.org/docs/)
- [TypeScript Handbook](https://www.typescriptlang.org/docs/)

### Guides et tutoriels
- [NestJS Best Practices](https://github.com/nestjs/nest/blob/master/CONTRIBUTING.md)
- [TypeORM Migrations Guide](https://typeorm.io/migrations)
- [PostgreSQL Performance Tips](https://wiki.postgresql.org/wiki/Performance_Optimization)

---

## 🤝 Contribution

Les contributions sont les bienvenues ! 

1. Fork le projet
2. Créez votre branche (`git checkout -b feature/AmazingFeature`)
3. Committez vos changements (`git commit -m 'Add: Amazing feature'`)
4. Push vers la branche (`git push origin feature/AmazingFeature`)
5. Ouvrez une Pull Request

---

## 📝 Changelog

### Version 1.0.0 (2025-01-20)
- ✨ Générateur CLI interactif
- 🔒 Configuration sécurisée par défaut
- 🐳 Support Docker complet
- 🧪 Tests unitaires et E2E
- 📝 Documentation complète

---

## 📄 Licence

Ce projet est sous licence MIT. Voir le fichier [LICENSE](LICENSE) pour plus de détails.

---

## 👨‍💻 Auteur

**Jacquinot**

- 📧 Email: [hiqaody@gmail.com](mailto:hiqaody@gmail.com)
- 🐙 GitHub: [@HiQaody](https://github.com/HiQaody)
- 💼 LinkedIn: [Votre LinkedIn](https://linkedin.com/in/votre-profile)

---

## ⭐ Support

Si ce projet vous aide, n'hésitez pas à lui donner une étoile sur GitHub !

<div align="center">

**🚀 Créez votre backend professionnel en 2 minutes !**

[![Star on GitHub](https://img.shields.io/github/stars/HiQaody/create-backend-pg.svg?style=social)](https://github.com/HiQaody/create-backend-pg)

</div>