Full-Stack Nest + Next.js Example

Great question! Here’s how your NestJS backend would look compared to the FastAPI structure. NestJS follows a more Angular-inspired, decorator-based architecture:

🟢 NestJS Backend Structure

backend/
├── src/
│   ├── main.ts                 # NestJS app entry point
│   ├── app.module.ts           # Root module
│   ├── app.controller.ts       # Root controller
│   ├── app.service.ts          # Root service
│   ├── config/                 # Configuration
│   │   ├── database.config.ts
│   │   ├── jwt.config.ts
│   │   └── app.config.ts
│   ├── modules/                # Feature modules
│   │   ├── users/
│   │   │   ├── users.module.ts
│   │   │   ├── users.controller.ts
│   │   │   ├── users.service.ts
│   │   │   ├── users.repository.ts
│   │   │   ├── dto/
│   │   │   │   ├── create-user.dto.ts
│   │   │   │   ├── update-user.dto.ts
│   │   │   │   └── user-response.dto.ts
│   │   │   ├── entities/
│   │   │   │   └── user.entity.ts
│   │   │   └── users.controller.spec.ts
│   │   ├── projects/
│   │   │   ├── projects.module.ts
│   │   │   ├── projects.controller.ts
│   │   │   ├── projects.service.ts
│   │   │   ├── projects.repository.ts
│   │   │   ├── dto/
│   │   │   │   ├── create-project.dto.ts
│   │   │   │   ├── update-project.dto.ts
│   │   │   │   └── project-response.dto.ts
│   │   │   ├── entities/
│   │   │   │   └── project.entity.ts
│   │   │   └── projects.controller.spec.ts
│   │   ├── soq/
│   │   │   ├── soq.module.ts
│   │   │   ├── soq.controller.ts
│   │   │   ├── soq.service.ts
│   │   │   ├── soq.repository.ts
│   │   │   ├── dto/
│   │   │   │   ├── create-soq.dto.ts
│   │   │   │   ├── update-soq.dto.ts
│   │   │   │   └── soq-response.dto.ts
│   │   │   ├── entities/
│   │   │   │   └── soq.entity.ts
│   │   │   └── soq.controller.spec.ts
│   │   ├── tenders/
│   │   │   ├── tenders.module.ts
│   │   │   ├── tenders.controller.ts
│   │   │   ├── tenders.service.ts
│   │   │   ├── tenders.repository.ts
│   │   │   ├── dto/
│   │   │   │   ├── create-tender.dto.ts
│   │   │   │   ├── update-tender.dto.ts
│   │   │   │   └── tender-response.dto.ts
│   │   │   ├── entities/
│   │   │   │   └── tender.entity.ts
│   │   │   └── tenders.controller.spec.ts
│   │   ├── escrow/
│   │   │   ├── escrow.module.ts
│   │   │   ├── escrow.controller.ts
│   │   │   ├── escrow.service.ts
│   │   │   ├── escrow.repository.ts
│   │   │   ├── dto/
│   │   │   │   ├── create-escrow.dto.ts
│   │   │   │   ├── update-escrow.dto.ts
│   │   │   │   └── escrow-response.dto.ts
│   │   │   ├── entities/
│   │   │   │   └── escrow.entity.ts
│   │   │   └── escrow.controller.spec.ts
│   │   └── audit/
│   │       ├── audit.module.ts
│   │       ├── audit.controller.ts
│   │       ├── audit.service.ts
│   │       ├── audit.repository.ts
│   │       ├── dto/
│   │       │   ├── create-audit.dto.ts
│   │       │   ├── update-audit.dto.ts
│   │       │   └── audit-response.dto.ts
│   │       ├── entities/
│   │       │   └── audit.entity.ts
│   │       └── audit.controller.spec.ts
│   ├── common/                 # Shared utilities
│   │   ├── decorators/
│   │   │   ├── roles.decorator.ts
│   │   │   └── current-user.decorator.ts
│   │   ├── guards/
│   │   │   ├── jwt-auth.guard.ts
│   │   │   └── roles.guard.ts
│   │   ├── interceptors/
│   │   │   ├── transform.interceptor.ts
│   │   │   └── logging.interceptor.ts
│   │   ├── filters/
│   │   │   └── http-exception.filter.ts
│   │   ├── pipes/
│   │   │   └── validation.pipe.ts
│   │   └── utils/
│   │       ├── email.util.ts
│   │       ├── file-upload.util.ts
│   │       └── validators.util.ts
│   ├── database/               # Database configuration
│   │   ├── database.module.ts
│   │   ├── entities/
│   │   │   ├── user.entity.ts
│   │   │   ├── project.entity.ts
│   │   │   ├── soq.entity.ts
│   │   │   ├── tender.entity.ts
│   │   │   ├── escrow.entity.ts
│   │   │   └── audit.entity.ts
│   │   └── migrations/
│   │       ├── 001-create-users.ts
│   │       ├── 002-create-projects.ts
│   │       ├── 003-create-soq.ts
│   │       ├── 004-create-tenders.ts
│   │       ├── 005-create-escrow.ts
│   │       └── 006-create-audit.ts
│   └── auth/                   # Authentication module
│       ├── auth.module.ts
│       ├── auth.controller.ts
│       ├── auth.service.ts
│       ├── jwt.strategy.ts
│       ├── local.strategy.ts
│       └── dto/
│           ├── login.dto.ts
│           └── register.dto.ts
├── test/                       # E2E tests
│   ├── app.e2e-spec.ts
│   ├── users.e2e-spec.ts
│   ├── projects.e2e-spec.ts
│   ├── soq.e2e-spec.ts
│   ├── tenders.e2e-spec.ts
│   ├── escrow.e2e-spec.ts
│   └── audit.e2e-spec.ts
├── dist/                       # Compiled output
├── node_modules/
├── package.json
├── package-lock.json
├── tsconfig.json
├── tsconfig.build.json
├── nest-cli.json
├── .env.example
├── .gitignore
├── Dockerfile
├── docker-compose.yml
└── README.md

---

�� Key Differences: FastAPI vs NestJS

Aspect	FastAPI	NestJS
Language	Python	TypeScript/JavaScript
Architecture	Function-based	Class-based, decorators
Structure	Flat modules	Feature modules
Validation	Pydantic models	DTOs with class-validator
Database	SQLAlchemy	TypeORM/Prisma
Testing	pytest	Jest
Dependency Injection	Manual	Built-in DI container
Guards/Interceptors	Dependencies	Built-in decorators

---

📝 Example: User Module in NestJS

src/modules/users/users.controller.ts

import { Controller, Get, Post, Body, Param, UseGuards } from '@nestjs/common';
import { UsersService } from './users.service';
import { CreateUserDto } from './dto/create-user.dto';
import { JwtAuthGuard } from '../../common/guards/jwt-auth.guard';
import { RolesGuard } from '../../common/guards/roles.guard';
import { Roles } from '../../common/decorators/roles.decorator';

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

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

  @Get()
  @Roles('admin', 'manager')
  findAll() {
    return this.usersService.findAll();
  }

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

src/modules/users/dto/create-user.dto.ts

import { IsEmail, IsString, IsEnum, IsOptional } from 'class-validator';

export class CreateUserDto {
  @IsString()
  name: string;

  @IsEmail()
  email: string;

  @IsString()
  phone: string;

  @IsEnum(['Project Owner', 'In-House User', 'Bidder'])
  role: string;

  @IsOptional()
  @IsString()
  entity?: string;

  @IsOptional()
  @IsString()
  category?: string;
}

src/modules/users/entities/user.entity.ts

import { Entity, PrimaryGeneratedColumn, Column, CreateDateColumn, UpdateDateColumn } from 'typeorm';

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

  @Column()
  name: string;

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

  @Column()
  phone: string;

  @Column({
    type: 'enum',
    enum: ['Project Owner', 'In-House User', 'Bidder'],
    default: 'Bidder'
  })
  role: string;

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

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

  @CreateDateColumn()
  createdAt: Date;

  @UpdateDateColumn()
  updatedAt: Date;
}

---

🚀 NestJS Benefits for Your Project

1. TypeScript First: Better type safety and IDE support
2. Modular Architecture: Clean separation of concerns
3. Built-in DI: Automatic dependency injection
4. Decorators: Clean, readable API definitions
5. Guards & Interceptors: Built-in middleware system
6. Validation: Class-validator integration
7. Testing: Jest integration out of the box

Would you like me to show you how to set up the NestJS equivalent of your current FastAPI structure?

---

1. File and Path Check

• File: src/content/docs/instruction/nestjs+nextjs.md
• Sidebar Slug: instruction/nestjs+nextjs
• Expected Path:
  • The slug is always relative to the docs root (src/content/docs/)
  • So, instruction/nestjs+nextjs → src/content/docs/instruction/nestjs+nextjs.md

You have this correct.

---

2. Case Sensitivity & Typos

• Make sure the filename is exactly nestjs+nextjs.md (all lowercase, no spaces, no hidden characters).
• Make sure the folder is exactly instruction (all lowercase).

---

3. Sidebar Config

• Your config should be:

  { label: 'Full-Stack Nest + Next.js Example', slug: 'instruction/nestjs+nextjs' }

• No .md in the slug.

---

4. Astro/Content Caching

• Restart your Astro dev server after any file or config changes.
• If you use pnpm, yarn, or npm, try:

  rm -rf .astro
  rm -rf node_modules/.vite
  npm run dev

  (or the equivalent for your package manager)

---

5. Check for Duplicate or Conflicting Files

• Make sure there is only one file named nestjs+nextjs.md in your entire src/content/docs/ tree.
• No uppercase variants, no .mdx with the same name.

---

6. Astro Version / Starlight Version

• If you recently upgraded Astro or Starlight, sometimes a full clean and reinstall helps:

  rm -rf node_modules
  rm package-lock.json # or yarn.lock or pnpm-lock.yaml
  npm install
  npm run dev

---

7. Check for Hidden Characters

• Sometimes, especially if the file was renamed in Finder or via copy-paste, there can be hidden characters.
• Run this in your project root to check:

  ls -l src/content/docs/instruction/

  Make sure the filename is exactly nestjs+nextjs.md.

---

8. Try Renaming the File

• Rename nestjs+nextjs.md to nestjs-nextjs.md
• Update the sidebar slug to instruction/nestjs-nextjs
• Restart the dev server

Sometimes the + character can cause issues in some static site generators or their routing logic.

---

9. Check for .mdx Extension

• If you accidentally created nestjs+nextjs.mdx, the slug would be different. Make sure the extension is .md.

---

10. Final: Minimal Sidebar Test

Try a minimal sidebar config with only this entry to isolate the problem:

sidebar: [
  {
    label: 'Instruction',
    items: [
      { label: 'Full-Stack Nest + Next.js Example', slug: 'instruction/nestjs+nextjs' }
    ]
  }
]

If this still fails, the issue is with file recognition, not config.

---

Summary of What to Try Next

1. Rename nestjs+nextjs.md → nestjs-nextjs.md
2. Update sidebar slug to instruction/nestjs-nextjs
3. Restart Astro dev server
4. If it works, the + was the problem.

---

Would you like me to automatically rename the file and update your config for you? This is the most likely fix!