Angular SSR

Angular v20+ で サーバーサイドレンダリング、ハイドレーション、プリレンダリングを実装します。

セットアップ

既存プロジェクトに SSR を追加

ng add @angular/ssr

以下が追加されます:

• @angular/ssr パッケージ
• server.ts - Express サーバー
• src/main.server.ts - サーバーブートストラップ
• src/app/app.config.server.ts - サーバープロバイダー
• angular.json に SSR 設定を追加

プロジェクト構成

src/
├── app/
│   ├── app.config.ts          # ブラウザ設定
│   ├── app.config.server.ts   # サーバー設定
│   └── app.routes.ts
├── main.ts                     # ブラウザブートストラップ
├── main.server.ts              # サーバーブートストラップ
server.ts                       # Express サーバー

設定

app.config.server.ts

import { ApplicationConfig, mergeApplicationConfig } from '@angular/core';
import { provideServerRendering } from '@angular/platform-server';
import { provideServerRoutesConfig } from '@angular/ssr';
import { appConfig } from './app.config';
import { serverRoutes } from './app.routes.server';

const serverConfig: ApplicationConfig = {
  providers: [
    provideServerRendering(),
    provideServerRoutesConfig(serverRoutes),
  ],
};

export const config = mergeApplicationConfig(appConfig, serverConfig);

サーバールート設定

// app.routes.server.ts
import { RenderMode, ServerRoute } from '@angular/ssr';

export const serverRoutes: ServerRoute[] = [
  {
    path: '',
    renderMode: RenderMode.Prerender, // ビルド時に静的生成
  },
  {
    path: 'products',
    renderMode: RenderMode.Prerender,
  },
  {
    path: 'products/:id',
    renderMode: RenderMode.Server, // 動的 SSR
  },
  {
    path: 'dashboard',
    renderMode: RenderMode.Client, // クライアントのみ (SPA)
  },
  {
    path: '**',
    renderMode: RenderMode.Server,
  },
];

レンダーモード

モード	説明	ユースケース
RenderMode.Prerender	ビルド時に静的 HTML を生成	マーケティングページ、ブログ
RenderMode.Server	リクエスト毎に動的 SSR	ユーザー固有のコンテンツ
RenderMode.Client	クライアント側のみ (SPA)	認証が必要なダッシュボード

ハイドレーション

デフォルトハイドレーション

ハイドレーションは provideClientHydration() で デフォルト有効です:

// app.config.ts
import { provideClientHydration } from '@angular/platform-browser';

export const appConfig: ApplicationConfig = {
  providers: [
    provideClientHydration(),
    // ...
  ],
};

インクリメンタルハイドレーション

特定のコンポーネントのハイドレーションを遅延させます:

@Component({
  template: `
    <!-- ビューポート内に入ったときにハイドレーション -->
    @defer (hydrate on viewport) {
      <app-comments [postId]="postId" />
    } @placeholder {
      <div class="comments-placeholder">Loading comments...</div>
    }
    
    <!-- ユーザー操作時にハイドレーション -->
    @defer (hydrate on interaction) {
      <app-interactive-chart [data]="chartData" />
    }
    
    <!-- ブラウザがアイドル時にハイドレーション -->
    @defer (hydrate on idle) {
      <app-recommendations />
    }
    
    <!-- ハイドレーションしない (静的のみ) -->
    @defer (hydrate never) {
      <app-static-footer />
    }
  `,
})
export class Post {
  postId = input.required<string>();
  chartData = input.required<ChartData>();
}

ハイドレーショントリガー

トリガー	説明
hydrate on viewport	要素がビューポート内に入ったとき
hydrate on interaction	クリック、フォーカス、入力時
hydrate on idle	ブラウザがアイドル時
hydrate on immediate	ロード直後
hydrate on timer(ms)	指定遅延後
hydrate when condition	式が true のとき
hydrate never	ハイドレーションしない (静的)

イベントリプレイ

ハイドレーション完了前にユーザーイベントをキャプチャします:

import { provideClientHydration, withEventReplay } from '@angular/platform-browser';

export const appConfig: ApplicationConfig = {
  providers: [
    provideClientHydration(withEventReplay()),
  ],
};

ブラウザ専用コード

プラットフォーム検出

import { PLATFORM_ID, inject } from '@angular/core';
import { isPlatformBrowser, isPlatformServer } from '@angular/common';

@Component({...})
export class My {
  private platformId = inject(PLATFORM_ID);
  
  ngOnInit() {
    if (isPlatformBrowser(this.platformId)) {
      // ブラウザ専用コード
      window.addEventListener('scroll', this.onScroll);
    }
  }
}

afterNextRender / afterRender

レンダリング後、ブラウザでのみコードを実行します:

import { afterNextRender, afterRender } from '@angular/core';

@Component({...})
export class Chart {
  constructor() {
    // 最初のレンダリング後に 1 回実行 (ブラウザのみ)
    afterNextRender(() => {
      this.initChart();
    });
    
    // すべてのレンダリング後に実行 (ブラウザのみ)
    afterRender(() => {
      this.updateChart();
    });
  }
  
  private initChart() {
    // ここでは DOM API を安全に使用できます
    const canvas = document.getElementById('chart');
    new Chart(canvas, this.config);
  }
}

ブラウザ API を安全に注入

// tokens.ts
import { InjectionToken, PLATFORM_ID, inject } from '@angular/core';
import { isPlatformBrowser } from '@angular/common';

export const WINDOW = new InjectionToken<Window | null>('Window', {
  providedIn: 'root',
  factory: () => {
    const platformId = inject(PLATFORM_ID);
    return isPlatformBrowser(platformId) ? window : null;
  },
});

export const LOCAL_STORAGE = new InjectionToken<Storage | null>('LocalStorage', {
  providedIn: 'root',
  factory: () => {
    const platformId = inject(PLATFORM_ID);
    return isPlatformBrowser(platformId) ? localStorage : null;
  },
});

// 使用方法
@Injectable({ providedIn: 'root' })
export class Storage {
  private storage = inject(LOCAL_STORAGE);
  
  get(key: string): string | null {
    return this.storage?.getItem(key) ?? null;
  }
  
  set(key: string, value: string): void {
    this.storage?.setItem(key, value);
  }
}

プリレンダリング

静的ルート

// app.routes.server.ts
export const serverRoutes: ServerRoute[] = [
  { path: '', renderMode: RenderMode.Prerender },
  { path: 'about', renderMode: RenderMode.Prerender },
  { path: 'contact', renderMode: RenderMode.Prerender },
  { path: 'blog', renderMode: RenderMode.Prerender },
];

getPrerenderParams を使った動的ルート

// app.routes.server.ts
import { RenderMode, ServerRoute, PrerenderFallback } from '@angular/ssr';

export const serverRoutes: ServerRoute[] = [
  {
    path: 'products/:id',
    renderMode: RenderMode.Prerender,
    async getPrerenderParams() {
      // プリレンダリングする商品 ID を取得
      const response = await fetch('https://api.example.com/products');
      const products = await response.json();
      return products.map((p: Product) => ({ id: p.id }));
    },
    fallback: PrerenderFallback.Server, // 非プリレンダリングは SSR
  },
  {
    path: 'blog/:slug',
    renderMode: RenderMode.Prerender,
    async getPrerenderParams() {
      const posts = await fetchBlogPosts();
      return posts.map(post => ({ slug: post.slug }));
    },
    fallback: PrerenderFallback.Client, // 非プリレンダリングは SPA
  },
];

プリレンダーフォールバックオプション

フォールバック	説明
PrerenderFallback.Server	非プリレンダリングルートは SSR
PrerenderFallback.Client	クライアント側レンダリング
PrerenderFallback.None	非プリレンダリングルートは 404

HTTP キャッシング

TransferState

HTTP レスポンスをサーバーからクライアントに自動転送します:

import { provideClientHydration, withHttpTransferCacheOptions } from '@angular/platform-browser';

export const appConfig: ApplicationConfig = {
  providers: [
    provideClientHydration(
      withHttpTransferCacheOptions({
        includePostRequests: true,
        includeRequestsWithAuthHeaders: false,
        filter: (req) => !req.url.includes('/api/realtime'),
      })
    ),
  ],
};

手動 TransferState

import { TransferState, makeStateKey } from '@angular/core';

const PRODUCTS_KEY = makeStateKey<Product[]>('products');

@Injectable({ providedIn: 'root' })
export class Product {
  private http = inject(HttpClient);
  private transferState = inject(TransferState);
  private platformId = inject(PLATFORM_ID);
  
  getProducts(): Observable<Product[]> {
    // サーバーから転送されたデータをチェック
    if (this.transferState.hasKey(PRODUCTS_KEY)) {
      const products = this.transferState.get(PRODUCTS_KEY, []);
      this.transferState.remove(PRODUCTS_KEY);
      return of(products);
    }
    
    return this.http.get<Product[]>('/api/products').pipe(
      tap(products => {
        // サーバーで転送するために保存
        if (isPlatformServer(this.platformId)) {
          this.transferState.set(PRODUCTS_KEY, products);
        }
      })
    );
  }
}

ビルドとデプロイ

ビルドコマンド

# SSR でビルド
ng build

# 出力構造
dist/
├── my-app/
│   ├── browser/      # クライアント資産
│   └── server/       # サーバーバンドル

SSR サーバーを実行

# 開発環境
npm run serve:ssr:my-app

# 本番環境
node dist/my-app/server/server.mjs

Node.js ホストにデプロイ

// server.ts (生成されたもの)
import { APP_BASE_HREF } from '@angular/common';
import { CommonEngine } from '@angular/ssr/node';
import express from 'express';
import { dirname, join, resolve } from 'node:path';
import { fileURLToPath } from 'node:url';
import bootstrap from './src/main.server';

const serverDistFolder = dirname(fileURLToPath(import.meta.url));
const browserDistFolder = resolve(serverDistFolder, '../browser');
const indexHtml = join(serverDistFolder, 'index.server.html');

const app = express();
const commonEngine = new CommonEngine();

app.get('*', express.static(browserDistFolder, { maxAge: '1y', index: false }));

app.get('*', (req, res, next) => {
  commonEngine
    .render({
      bootstrap,
      documentFilePath: indexHtml,
      url: req.originalUrl,
      publicPath: browserDistFolder,
      providers: [{ provide: APP_BASE_HREF, useValue: req.baseUrl }],
    })
    .then((html) => res.send(html))
    .catch((err) => next(err));
});

app.listen(4000, () => {
  console.log('Server listening on http://localhost:4000');
});

詳細なパターンについては、references/ssr-patterns.md を参照してください。