backend-nodejs

name	backend-nodejs
description	Node.js/TypeScript backend expert. Handles Express/Fastify API routes, TypeScript strict mode, Prisma ORM, Zod validation, error handling, configuration management. Use when project is Node.js backend (package.json + TypeScript server).
allowed-tools	Read, Write, Edit, Bash, Glob, Grep

Backend Node.js Skill - API Development Expert

Expert backend Node.js/TypeScript pour API REST + GraphQL

Inspiré de : Vercel API design, Stripe backend patterns, Prisma best practices

---

Scope

Chargé par: executor agent (SI projet Node.js détecté)

Détection auto:

• Fichier package.json existe
• Fichiers server.ts ou index.ts ou src/server.ts
• Dependencies: express, fastify, @prisma/client, etc

Stack supporté:

• Runtime: Node.js 18+ / Bun
• Language: TypeScript (strict mode)
• Frameworks: Express, Fastify, Hono
• Database: Prisma ORM
• Validation: Zod
• Testing: Vitest, Jest

---

Conventions Strictes

1. Structure Projet (Obligatoire)

backend/
├── src/
│   ├── config/
│   │   └── env.ts           # Configuration centralisée (1 seul fichier)
│   ├── routes/
│   │   ├── index.ts         # Router principal
│   │   ├── tasks.ts
│   │   └── users.ts
│   ├── services/
│   │   ├── task.service.ts  # Business logic
│   │   └── user.service.ts
│   ├── middleware/
│   │   ├── auth.ts
│   │   ├── error.ts
│   │   └── validation.ts
│   ├── types/
│   │   └── index.ts         # TypeScript types partagés
│   ├── lib/
│   │   ├── prisma.ts        # Prisma client singleton
│   │   └── logger.ts
│   └── server.ts            # Entry point
├── prisma/
│   └── schema.prisma
├── package.json
├── tsconfig.json
└── .env

---

2. Configuration (1 seul fichier - 12-Factor App)

// src/config/env.ts
import { z } from 'zod'

const envSchema = z.object({
  NODE_ENV: z.enum(['development', 'production', 'test']).default('development'),
  PORT: z.string().default('3000'),
  DATABASE_URL: z.string(),
  JWT_SECRET: z.string().min(32),
  CORS_ORIGIN: z.string().default('http://localhost:3000'),
  LOG_LEVEL: z.enum(['debug', 'info', 'warn', 'error']).default('info'),
})

export const env = envSchema.parse(process.env)

export type Env = z.infer<typeof envSchema>

Principe: Validation config au démarrage, crash immédiat si config invalide.

---

3. Prisma Client Singleton (Pattern Vercel)

// src/lib/prisma.ts
import { PrismaClient } from '@prisma/client'
import { env } from '@/config/env'

const globalForPrisma = globalThis as unknown as {
  prisma: PrismaClient | undefined
}

export const prisma =
  globalForPrisma.prisma ??
  new PrismaClient({
    log: env.NODE_ENV === 'development'
      ? ['query', 'error', 'warn']
      : ['error'],
  })

if (env.NODE_ENV !== 'production') {
  globalForPrisma.prisma = prisma
}

Interdiction: Créer plusieurs instances PrismaClient (épuise connexions DB).

---

4. Routes Pattern (Express)

// src/routes/tasks.ts
import { Router } from 'express'
import { z } from 'zod'
import { taskService } from '@/services/task.service'
import { validateRequest } from '@/middleware/validation'
import { requireAuth } from '@/middleware/auth'

const router = Router()

// Zod schemas
const createTaskSchema = z.object({
  body: z.object({
    title: z.string().min(1).max(200),
    description: z.string().optional(),
    status: z.enum(['PENDING', 'IN_PROGRESS', 'COMPLETED']).default('PENDING'),
  }),
})

// Routes
router.post(
  '/',
  requireAuth,
  validateRequest(createTaskSchema),
  async (req, res, next) => {
    try {
      const task = await taskService.createTask(req.user., req.)
      res.().(task)
    }  (error) {
      (error)
    }
  }
)

router.(
  ,
  requireAuth,
   (req, res, next) => {
     {
       tasks =  taskService.(req..)
      res.(tasks)
    }  (error) {
      (error)
    }
  }
)

router.(
  ,
  requireAuth,
  (z.({
    : z.({ : z.().() }),
    : createTaskSchema...(),
  })),
   (req, res, next) => {
     {
       task =  taskService.(
        req..,
        req..,
        req.
      )
      res.(task)
    }  (error) {
      (error)
    }
  }
)

  router

Pattern: Routes légères → Business logic dans services.

---

5. Services Pattern (Singleton + Business Logic)

// src/services/task.service.ts
import { prisma } from '@/lib/prisma'
import { TaskStatus } from '@prisma/client'

export class TaskService {
  async createTask(
    userId: string,
    data: { title: string; description?: string; status?: TaskStatus }
  ) {
    // Business logic validation
    const existingCount = await prisma.task.count({
      where: { userId, status: 'PENDING' },
    })

    if (existingCount >= 100) {
      throw new Error('Maximum pending tasks limit reached')
    }

    // Create with transaction if multiple operations
    return prisma.task.create({
      data: {
        ...data,
        userId,
      },
      include: {
        user: {
          select: { id: true, name: true, email: true },
        },
      },
    })
  }

  async getTasks(: ) {
     prisma..({
      : { userId },
      : {
        : {
          : { : , :  },
        },
      },
      : { :  },
    })
  }

   () {
    
     task =  prisma..({
      : { id },
      : { :  },
    })

     (!task || task. !== userId) {
        ()
    }

     prisma..({
      : { id },
      data,
    })
  }

   () {
    
     task =  prisma..({
      : { id },
      : { :  },
    })

     (!task || task. !== userId) {
        ()
    }

     prisma..({
      : { id },
    })
  }
}


  taskService =  ()

Principe: 1 service = 1 ressource, toute business logic centralisée.

---

6. Error Handling Middleware (Standardisé)

// src/middleware/error.ts
import { Request, Response, NextFunction } from 'express'
import { ZodError } from 'zod'
import { Prisma } from '@prisma/client'
import { logger } from '@/lib/logger'

export class AppError extends Error {
  constructor(
    message: string,
    public statusCode: number = 500,
    public type: string = 'server_error'
  ) {
    super(message)
  }
}

export function errorHandler(
  error: Error,
  req: Request,
  res: Response,
  next: NextFunction
) {
  // Zod validation error
  if (error instanceof ZodError) {
    return res.status().({
      : ,
      : ,
      : error..( ({
        : e..(),
        : e.,
      })),
    })
  }

  
   (error  .) {
     (error. === ) {
       res.().({
        : ,
        : ,
      })
    }
     (error. === ) {
       res.().({
        : ,
        : ,
      })
    }
  }

  
   (error  ) {
     res.(error.).({
      : error.,
      : error.,
    })
  }

  
  logger.(, error)
   res.().({
    : ,
    : ,
  })
}

---

7. Validation Middleware (Zod)

// src/middleware/validation.ts
import { Request, Response, NextFunction } from 'express'
import { AnyZodObject, ZodError } from 'zod'

export function validateRequest(schema: AnyZodObject) {
  return async (req: Request, res: Response, next: NextFunction) => {
    try {
      await schema.parseAsync({
        body: req.body,
        query: req.query,
        params: req.params,
      })
      next()
    } catch (error) {
      if (error instanceof ZodError) {
        return res.status(400).json({
          message: 'Validation error',
          type: 'validation_error',
          errors: error.errors.map( => ({
            : e..(),
            : e.,
          })),
        })
      }
      (error)
    }
  }
}

---

8. Server Entry Point

// src/server.ts
import express from 'express'
import cors from 'cors'
import helmet from 'helmet'
import { env } from '@/config/env'
import { errorHandler } from '@/middleware/error'
import { logger } from '@/lib/logger'
import router from '@/routes'

const app = express()

// Security middleware
app.use(helmet())
app.use(cors({ origin: env.CORS_ORIGIN }))
app.use(express.json({ limit: '10mb' }))

// Health check
app.get('/health', (req, res) => {
  res.json({ status: 'ok', timestamp: new Date().toISOString() })
})

// API routes
app.use('/api', router)

// Error handler (MUST be last)
app.use(errorHandler)


 server = app.(env.,  {
  logger.()
  logger.()
})


process.(,  {
  logger.()
  server.( {
    logger.()
    process.()
  })
})

  app

---

9. TypeScript Config (Strict Mode)

// tsconfig.json
{
  "compilerOptions": {
    "target": "ES2022",
    "module": "ESNext",
    "moduleResolution": "bundler",
    "lib": ["ES2022"],
    "outDir": "./dist",
    "rootDir": "./src",
    "strict": true,
    "esModuleInterop": true,
    "skipLibCheck": true,
    "forceConsistentCasingInFileNames": true,
    "resolveJsonModule": true,
    "isolatedModules": 
     
     
     
     
     
       
    
  
   
    

---

Naming Conventions

Variables & Functions (camelCase)

const userId = "123"
const currentUser = await getUser()

async function createTask() {}
async function getUserTasks() {}

Classes & Types (PascalCase)

class TaskService {}
type TaskResponse = {}
interface UserData {}

Files (kebab-case)

task.service.ts
user.controller.ts
auth.middleware.ts

Constants (SCREAMING_SNAKE_CASE)

const MAX_TASKS_PER_USER = 100
const DEFAULT_PAGE_SIZE = 20

---

Anti-Patterns à Éviter

❌ Multiple PrismaClient instances

// ❌ INTERDIT
const prisma = new PrismaClient()  // Dans chaque fichier

✅ Singleton pattern

// ✅ CORRECT
import { prisma } from '@/lib/prisma'

---

❌ Business logic dans routes

// ❌ INTERDIT
router.post('/', async (req, res) => {
  const task = await prisma.task.create({ data: req.body })
  res.json(task)
})

✅ Business logic dans services

// ✅ CORRECT
router.post('/', async (req, res) => {
  const task = await taskService.createTask(req.user.id, req.body)
  res.json(task)
})

---

❌ Pas de validation

// ❌ INTERDIT
router.post('/', async (req, res) => {
  const task = await taskService.createTask(req.body)  // Pas de validation
})

✅ Zod validation middleware

// ✅ CORRECT
router.post('/', validateRequest(createTaskSchema), async (req, res) => {
  const task = await taskService.createTask(req.body)
})

---

❌ Errors non catchés

// ❌ INTERDIT
router.get('/', async (req, res) => {
  const tasks = await taskService.getTasks()  // Crash si erreur
})

✅ Try/catch + next(error)

// ✅ CORRECT
router.get('/', async (req, res, next) => {
  try {
    const tasks = await taskService.getTasks()
    res.json(tasks)
  } catch (error) {
    next(error)  // Error handler middleware
  }
})

---

Checklist Feature API

Avant créer route:

• Service existe? (anti-duplication)
• Zod schema défini?
• Auth middleware si protected?
• Error handling (try/catch + next)?

Après créer route:

• Route exportée dans routes/index.ts?
• Types TypeScript définis?
• Ownership checks (si user data)?

---

Exemples Complets

Exemple 1: CRUD Tasks API

Structure créée:

src/
├── routes/tasks.ts          # Routes HTTP
├── services/task.service.ts # Business logic
├── types/task.ts            # TypeScript types

Workflow:

1. Zod schema validation
2. Route appelle service
3. Service utilise Prisma
4. Error handling middleware

---

Exemple 2: Auth Middleware

// src/middleware/auth.ts
import { Request, Response, NextFunction } from 'express'
import jwt from 'jsonwebtoken'
import { env } from '@/config/env'
import { AppError } from '@/middleware/error'

declare global {
  namespace Express {
    interface Request {
      user: { id: string; email: string }
    }
  }
}

export async function requireAuth(
  req: Request,
  res: Response,
  next: NextFunction
) {
  try {
    const token = req.headers.authorization?.replace('Bearer ', '')

    if (!token) {
      throw new AppError('Authentication required', 401, 'auth_error')
    }

     decoded = jwt.(token, env.)  {
      : 
      : 
    }

    req. = decoded
    ()
  }  (error) {
     (error  jwt.) {
       ( (, , ))
    }
    (error)
  }
}

---

Workflow Executor avec Backend-Node Skill

Détection auto:

1. executor scan projet
2. Trouve package.json + src/server.ts
3. Load backend-nodejs skill (au lieu de backend Python)
4. Applique conventions Node.js/TypeScript

Feature création:

User: "Crée CRUD tasks API"

executor:
1. Load skills: backend-nodejs + frontend + integration
2. Crée structure selon conventions Node.js
3. Zod validation + Prisma + Express routes
4. Services singleton pattern
5. Error handling standardisé

---

Principes

1. TypeScript Strict Mode - Zéro any, types partout
2. Configuration Centralisée - 1 seul env.ts (12-Factor App)
3. Services Singleton - 1 service par ressource, réutilisable
4. Validation Zod - Toutes inputs validées
5. Error Handling Standardisé - Errors structurés + types
6. Prisma Best Practices - Singleton client, select optimization
7. Separation of Concerns - Routes → Services → Prisma

Inspiré de:

• Vercel API Routes design
• Stripe backend architecture (services pattern)
• Prisma documentation (singleton, transactions)
• Express.js best practices

---

Version: 1.0.0 Created: 2025-01-10 Maintained by: executor agent (loaded si projet Node.js détecté)