@nestjs-ssr/react

React SSR for NestJS. One app. One deploy. Full type safety from database to DOM.

No separate frontend. No second router. No type boundary you maintain by hand. Controllers return data, components render it, TypeScript enforces the contract.

Documentation | Get Started

The whole contract in two files

// recipes.controller.ts
import { Controller, Get, Param } from '@nestjs/common';
import { Render, Layout } from '@nestjs-ssr/react';
import { RecipesLayout } from './views/recipes-layout';
import { RecipeDetail } from './views/recipe-detail';

@Controller('recipes')
@Layout(RecipesLayout)
export class RecipesController {
  @Get(':slug')
  @Render(RecipeDetail)
  getRecipe(@Param('slug') slug: string) {
    const recipe = this.recipes.findBySlug(slug);
    return {
      recipe,
      chef: this.chefs.findById(recipe.chefId),
      head: { title: recipe.name },
    };
  }
}

// recipe-detail.tsx
import { PageProps } from '@nestjs-ssr/react';

export default function RecipeDetail({
  recipe,
  chef,
}: PageProps<RecipeDetailProps>) {
  return (
    <article>
      <h1>{recipe.name}</h1>
      <p>{recipe.description}</p>
      <IngredientList items={recipe.ingredients} />
      <ChefCard chef={chef} />
    </article>
  );
}

Return the wrong shape and TypeScript catches it before the code runs.

Nothing breaks

Your NestJS app stays exactly as it is. Routing, guards, pipes, interceptors, services, modules, testing — all unchanged. You're adding a view layer, not rewriting your backend.

Everything improves

• One type, both sides — controller return type is the component's props. Change one, the other breaks at build time.
• Layouts that stay put — nested layouts persist across navigations. Header, sidebar, shell — rendered once, never re-mounted.
• No full reloads — link clicks fetch only the changed segment. State, scroll position, animations stay alive.
• Stream or string — renderToString for simplicity, renderToPipeableStream for performance. Suspense boundaries stream as they resolve.
• SEO out of the box — title, meta, Open Graph, JSON-LD. Return head from your controller.
• Vite HMR — instant updates, no page refresh. Works with Express and Fastify.

Add it to an existing NestJS app

npx @nestjs-ssr/react init

One command. Works with Express and Fastify, on NestJS 11 and 12. It adds a starter layout and a /welcome page so you can see server rendering and hydration working right away.

Requirements

Node.js 22.17+ / NestJS 11 or 12 / React 19+ / Vite 7+ / TypeScript 5+

Documentation

georgialexandrov.github.io/nestjs-ssr

• Installation
• Rendering
• Layouts
• Client-Side Navigation
• Request Context
• Configuration
• API Reference
• Performance
• Upgrading from 0.3

Contributing

git clone https://github.com/georgialexandrov/nestjs-ssr.git
cd nestjs-ssr
pnpm install
pnpm build:package
pnpm test

License

MIT