home / skills / hoangnguyen0403 / agent-skills-standard / ssr

ssr skill

This skill helps implement server-side rendering practices by guiding hydration, transfer state, and prerendering for React and Next.js apps.

npx playbooks add skill hoangnguyen0403/agent-skills-standard --skill ssr

Review the files below or copy the command above to add this skill to your agents.

Files (2)

SKILL.md

942 B

---
name: SSR (Server-Side Rendering)
description: Hydration, TransferState, and Prerendering standards.
metadata:
  labels: [angular, ssr, hydration, server-side]
  triggers:
    files: ['**/*.server.ts', 'server.ts']
    keywords: [hydration, transferState, afterNextRender, isPlatformServer]
---

# SSR (Server-Side Rendering)

## **Priority: P2 (MEDIUM)**

## Principles

- **Hydration**: Enable Client Hydration in `app.config.ts`.
- **Platform Checks**: Use `afterNextRender` or `afterRender` for browser-only code (e.g., accessing `window`).
- **TransferState**: Use `makeStateKey` and `TransferState` to prevent double-fetching data on client.

## Guidelines

- **Browser Objects**: Never access `window`, `document`, or `localStorage` directly in component logic. Implement abstractions or use `afterNextRender`.
- **Prerendering**: Use SSG for static pages (Marketing, Blogs).

## References

- [Hydration](references/hydration.md)

Overview

This skill codifies server-side rendering (SSR) best practices focused on hydration, TransferState, and prerendering. It guides TypeScript and framework-specific implementations to avoid client/server pitfalls and to optimize first-load performance. The goal is predictable hydration behavior, no duplicate data fetches, and appropriate use of static generation.

How this skill works

The skill inspects rendering flows and recommends enabling client hydration in app configuration so server-rendered markup becomes interactive. It enforces platform checks by suggesting afterRender/afterNextRender hooks for browser-only code and prescribes TransferState patterns (makeStateKey + TransferState) to serialize server-fetched data to the client and prevent double-fetching. It also directs when to use prerendering/SSG for static content.

When to use it

When pages are server-rendered and need to become interactive on the client (hydration).
When server-fetched data should be reused on the client to avoid duplicate API calls.
When browser globals (window/document/localStorage) may be referenced inside components.
When deciding between SSR and SSG for marketing pages, blogs, or other static content.
When optimizing first contentful paint and avoiding unnecessary runtime data requests.

Best practices

Enable client hydration in app configuration and verify hydration consistency across server and client renders.
Wrap browser-only logic inside afterRender/afterNextRender lifecycle hooks or platform checks to prevent server errors.
Use TransferState with makeStateKey to serialize server results and read them on the client to avoid re-fetching.
Never access window, document, or localStorage directly in shared component logic; use abstractions or DI wrappers.
Prefer SSG/prerendering for purely static pages (marketing, documentation, blogs) to improve cacheability and reduce server load.

Example use cases

Pre-rendering a marketing landing page with SSG and using TransferState for any server-derived personalization.
Rendering a product detail page on the server, hydrating interactive widgets on the client, and storing initial product data via TransferState.
Protecting component code that uses localStorage by running it only inside afterNextRender to avoid SSR reference errors.
Converting a blog site to prerendered pages while using SSR for user-specific dashboards.

FAQ

What is TransferState and when should I use it?

TransferState serializes server-fetched data into the HTML so the client can reuse it on hydration, preventing duplicate API calls. Use it whenever you fetch data on the server that will also be needed immediately by client code.

How do I avoid referencing window or document during SSR?

Avoid direct access in shared code. Use platform checks or run browser-only code inside afterRender/afterNextRender hooks or inject an abstraction that safely returns undefined on the server.