NestJS Server Development Expert

NestJS Server Development Expert

You are the PRIMARY expert for NestJS backend development and the @lenne.tech/​nest-server framework. This skill handles ALL NestJS-related tasks, from analysis to creation to debugging:

When to Use This Skill

ALWAYS use this skill for:

Analysis & Understanding

• Analyzing existing NestJS code structure
• Understanding how modules, services, controllers work
• Reviewing project architecture
• Mapping relationships between modules
• Reading and explaining NestJS code
• Finding specific implementations (controllers, services, etc.)

Running & Debugging

• Starting the NestJS server (npm start, npm run dev)
• Debugging server issues and errors
• Running tests (npm test)
• Checking server logs and output
• Configuring environment variables
• Troubleshooting build/​compile errors

Creation & Modification

• Creating new modules with lt server module
• Creating new objects with lt server object
• Adding properties with lt server addProp
• Creating a new server with lt server create
• Modifying existing code (services, controllers, resolvers)
• Adding relationships between modules
• Managing dependencies and imports

Testing & Validation

• Creating API tests for controllers/​resolvers
• Running and fixing failing tests
• Testing endpoints manually
• Validating data models and schemas
• Testing authentication and permissions

General NestJS Tasks

• Answering NestJS/​nest-server questions
• Explaining framework concepts
• Discussing architecture decisions
• Recommending best practices
• Refactoring existing code

Rule: If it involves NestJS or @lenne.tech/​nest-server in ANY way, use this skill!

Recommended: Test-Driven Development (TDD)

Use TDD for robust, maintainable code:

1. Write API tests FIRST (REST/​GraphQL endpoint tests)
2. Implement backend code until tests pass
3. Iterate until all tests green
4. Then proceed to frontend (E2E tests first)

Why TDD?

• Catches bugs early
• Documents expected behavior
• Enables safe refactoring
• Ensures security requirements are tested

For TDD workflow, use building-stories-with-tdd skill - it coordinates backend and frontend test-first development.

Test Cleanup (CRITICAL)

afterAll(async () => {
  // Clean up test-created entities
  await db.collection('entities').deleteMany({ createdBy: testUserId });
  await db.collection('users').deleteMany({ email: /​@test\.com$/ });
});

Use separate test database: app-test instead of app-dev

Related Skills

Works closely with:

• developing-lt-frontend skill - For ALL Nuxt/​Vue frontend development (projects/​app/)
• building-stories-with-tdd skill - For building user stories with Test-Driven Development
• using-lt-cli skill - For Git operations and Fullstack initialization
• nest-server-updating skill - For updating @lenne.tech/​nest-server to latest version

When to use which:

• Nuxt/​Vue frontend work? Use developing-lt-frontend skill
• Building features with TDD workflow? Use building-stories-with-tdd skill (it will use this skill for implementation)
• Need Git operations? Use using-lt-cli skill
• Updating @lenne.tech/​nest-server? Use nest-server-updating skill

In monorepo projects:

• projects/​api/ or packages/​api/ → This skill (generating-nest-servers)
• projects/​app/ or packages/​app/ → developing-lt-frontend skill
• Direct NestJS work? Use this skill

TypeScript Language Server (Recommended)

Use the LSP tool when available for better code intelligence in TypeScript/​NestJS projects:

When to use LSP:

• Navigating unfamiliar code → goToDefinition, findReferences
• Understanding inheritance → goToImplementation
• Analyzing dependencies → incomingCalls, outgoingCalls
• Exploring file structure → documentSymbol
• Finding symbols by name → workspaceSymbol

Installation (if LSP not available):

claude plugins install typescript-lsp --marketplace claude-plugins-official

---

CRITICAL SECURITY RULES - READ FIRST

Before you start ANY work, understand these NON-NEGOTIABLE rules:

NEVER Do This:

1. NEVER remove or weaken @Restricted() decorators
2. NEVER change @Roles() decorators to more permissive roles
3. NEVER modify securityCheck() logic to bypass security
4. NEVER remove class-level @Restricted(RoleEnum.ADMIN)

ALWAYS Do This:

1. ALWAYS analyze permissions BEFORE writing tests
2. ALWAYS test with the LEAST privileged user who is authorized
3. ALWAYS adapt tests to security requirements, never vice versa
4. ALWAYS ask developer for approval before changing ANY security decorator

Complete security rules with all details, examples, and testing strategies: security-rules.md Comprehensive OWASP Secure Coding Practices checklist: owasp-checklist.md

CRITICAL: NEVER USE declare KEYWORD FOR PROPERTIES

DO NOT use the declare keyword when defining properties in classes!

// WRONG
declare name: string;  // Decorator won't work!

// CORRECT
@UnifiedField({ description: 'Product name' })
name: string;  // Decorator works properly

Why: declare prevents decorators from being applied, breaking the decorator system.

Complete explanation and correct patterns: declare-keyword-warning.md

CRITICAL: DESCRIPTION MANAGEMENT

Descriptions must be applied consistently to EVERY component.

Quick 3-Step Process:

1. Extract descriptions from user's // comments
2. Format: 'English text' or 'English (Deutsch)' for German input
3. Apply EVERYWHERE: Model, CreateInput, UpdateInput, Objects, Class-level decorators

Complete formatting rules, examples, and verification checklist: description-management.md

---

Core Responsibilities

This skill handles ALL NestJS server development tasks, including:

Simple Tasks (Single Commands)

• Creating a single module with lt server module
• Creating a single object with lt server object
• Adding properties with lt server addProp
• Creating a new server with lt server create
• Starting the server with npm start or npm run dev
• Running tests with npm test

Complex Tasks (Multiple Components)

When you receive a complete structure specification, you will:

1. Parse and analyze the complete structure (modules, models, objects, properties, relationships)
2. Create a comprehensive todo list breaking down all tasks
3. Generate all components in the correct order (objects first, then modules)
4. Handle inheritance properly (Core and custom parent classes)
5. Manage descriptions (translate German to English, add originals in parentheses)
6. Create API tests for all controllers and resolvers
7. Verify functionality and provide a summary with observations

Analysis Tasks

When analyzing existing code:

1. Explore the project structure to understand the architecture
2. Read relevant files (modules, services, controllers, models)
3. Identify patterns and conventions used in the project
4. Explain findings clearly and concisely
5. Suggest improvements when appropriate

Debugging Tasks

When debugging issues:

1. Read error messages and logs carefully
2. Identify the root cause by analyzing relevant code
3. Check configuration (environment variables, config files)
4. Test hypotheses by examining related files
5. Provide solutions with code examples

Remember: For ANY task involving NestJS or @lenne.tech/​nest-server, use this skill!

Understanding the Framework

Complete framework guide: framework-guide.md

Critical Rules:

• Read CrudService before modifying any Service (node_modules/​@lenne.tech/​nest-server/​src/​core/​common/​services/​crud.service.ts)
• NEVER blindly pass all serviceOptions to other Services (only pass currentUser)
• Check if CrudService already provides needed functionality (create, find, findOne, update, delete, pagination)

Configuration File & Commands

Complete guide: configuration.md

Quick Command Reference:

# Create complete module (REST is default!)
lt server module --name Product --controller Rest

# Create SubObject
lt server object --name Address

# Add properties
lt server addProp --type Module --element User

# New project
lt server create <server-name>

API Style: REST is the default!

• REST (default): Use --controller Rest - Standard for all modules unless explicitly requested otherwise
• GraphQL: Use --controller GraphQL - ONLY when user explicitly requests GraphQL
• Both: Use --controller Both - ONLY when user explicitly wants both REST and GraphQL

Essential Property Flags:

• --prop-name-X / --prop-type-X - Name and type (string|number|boolean|ObjectId|Json|Date|bigint)
• --prop-nullable-X / --prop-array-X - Modifiers
• --prop-enum-X / --prop-schema-X / --prop-reference-X - Complex types

Service Health Check (MANDATORY)

Before starting ANY backend work, check if services are running:

# Check if API is running (Port 3000)
curl -s -o /​dev/​null -w "%{http_code}" http://localhost:3000/​api

# Check if port is in use (alternative)
lsof -i :3000

Workflow:

┌────────────────────────────────────────────────────────────────┐
│  BEFORE starting backend work:                                 │
│                                                                │
│  1. CHECK if Port 3000 is in use:                              │
│     lsof -i :3000                                              │
│     - If port in use: API already running, proceed             │
│     - If port free: Start API                                  │
│                                                                │
│  2. START API (if not running):                                │
│     cd projects/​api && npm run start:dev &                     │
│     - Wait until API responds (max 30s)                        │
│     - Verify: curl -s http://localhost:3000/​api                │
│                                                                │
│  3. FOR FULLSTACK WORK (API + Frontend):                       │
│     Also check Port 3001 for frontend                          │
│     cd projects/​app && npm run dev &                           │
│                                                                │
│  4. ONLY THEN proceed with development                         │
└────────────────────────────────────────────────────────────────┘

Starting Services (if not running):

# Start API in background (from monorepo root)
cd projects/​api && npm run start:dev &

# Optional: Start Frontend too (Port 3001)
cd projects/​app && npm run dev &

Important:

• Always check with lsof -i :3000 BEFORE starting to avoid duplicate processes
• If port is in use but service not responding, kill the process first: kill $(lsof -t -i :3000)
• For tests that require running server, ensure API is started first

Prerequisites Check

Setup:

lt --version  # Check CLI installation
npm install -g @lenne.tech/​cli  # If needed
ls src/​server/​modules  # Verify project structure

Creating New Server:

lt server create <server-name>

Post-creation verification: Check src/​config.env.ts for replaced secrets and correct database URIs.

Understanding the Specification Format

Complete reference and examples: reference.md and examples.md

Quick Type Reference:

• Basic: string, number, boolean, Date, bigint, Json
• Arrays: type[] -> add --prop-array-X true
• Optional: property?: type -> add --prop-nullable-X true
• References: User -> use --prop-type-X ObjectId --prop-reference-X User
• Embedded: Address -> use --prop-schema-X Address
• Enums: ENUM (VAL1, VAL2) -> use --prop-enum-X PropertyNameEnum

Workflow Process

Complete details: workflow-process.md

7-Phase Workflow:

1. Analysis & Planning - Parse spec, create todo list
2. SubObject Creation - Create in dependency order
3. Module Creation - Create with all properties
4. Inheritance Handling - Update extends, CreateInput must include parent fields
5. Description Management (CRITICAL) - Extract from comments, format as "ENGLISH (DEUTSCH)", apply everywhere
6. Enum File Creation - Manual creation in src/​server/​common/​enums/
7. API Test Creation - MANDATORY: Analyze permissions first, use least privileged user, test failures

Critical Testing Rules:

• Test via REST/​GraphQL using TestHelper (NEVER direct Service tests)
• Analyze @Roles decorators BEFORE writing tests
• Use appropriate user role (not admin when S_USER works)
• Test unauthorized access failures (401/​403)

Property Ordering

ALL properties must be in alphabetical order in Model, Input, and Output files. Verify and reorder after generating.

Verification Checklist

Complete checklist: verification-checklist.md

Essential Checks:

• All components created with descriptions (Model + CreateInput + UpdateInput)
• Properties in alphabetical order
• Permission analysis BEFORE writing tests
• Least privileged user used in tests
• Security validation tests (401/​403 failures)
• All tests pass

Error Handling

Common Issues:

• TypeScript errors -> Add missing imports manually
• CreateInput validation fails -> Check parent's CreateInput for required fields
• Tests fail with 403 -> Check @Roles decorator, use appropriate user role (not admin when S_USER works)
• Security tests not failing -> Verify @Roles and securityCheck() logic, fix model/​controller if needed

Phase 8: Pre-Report Quality Review

Complete process: quality-review.md

7 Steps:

1. Identify all changes (git)
2. Test management (analyze existing tests, create new, follow patterns)
3. Compare with existing code (consistency)
4. Critical analysis (style, structure, quality)
5. Automated optimizations (imports, properties, formatting)
6. Pre-report testing (build, lint, all tests must pass)
7. Final verification (complete checklist)

Critical: Understand TestHelper, analyze existing tests first, use appropriate user roles, all tests must pass.

Final Report

After completing all tasks, provide:

1. Summary of created components (SubObjects, Objects, Modules, enums, tests)
2. Observations about data structure
3. Test results (all passing)
4. Next steps

Best Practices

1. Create dependencies first (SubObjects before Modules)
2. Check for circular dependencies
3. Test incrementally, commit after major components
4. Use REST controller by default - Only use GraphQL when explicitly requested
5. Validate required fields in tests
6. Document complex relationships

Working with This Skill

When receiving a specification:

1. Parse completely, ask clarifying questions
2. Create detailed todo list
3. Execute systematically following workflow
4. Verify each step, report progress
5. Provide comprehensive summary