🚛

Zod Codecs で 'use client' を介した Server-Client 間データ転送を強化する

Honey32

2025/09/25に公開

React

zod

tech

'use client' は、サーバーからクライアントへと、描画用データを送信する境界を表すマーカーである ということは、広く知られています。

上記の記事の中では軽く触れるだけにとどめましたが、実は、 'use client' は「素の JSON」よりも多種多様なデータの転送に対応しています。

RSC が「サーバー側 / ブラウザ側のコードをシームレスに繋ぎ合わせる」技術であることが良くわかりますね。

サーバコンポーネントからクライアントコンポーネントに渡される props の値は、シリアライズ可能 (serializable) である必要があります。

シリアライズ可能な props には以下のものがあります：

プリミティブ

文字列

数値

bigint

ブーリアン

undefined

null

シンボル、ただし Symbol.for を通じてグローバルシンボルレジストリに登録されたシンボルのみ

シリアライズ可能な値を含んだ Iterable

文字列

配列

Map

Set

TypedArray と ArrayBuffer

Date

プレーンなオブジェクト: オブジェクト初期化子で作成され、シリアライズ可能なプロパティを持つもの

サーバアクション (server action) としての関数

クライアントまたはサーバコンポーネントの要素（JSX）

プロミス

出典:

`'use client'` だけで Date を送れる

先ほど述べた通り、 'use client' でマークされた Client Component に、Server Component から Date オブジェクトを渡すことは可能です。

以下の例では、 Date をサーバーからクライアントに送る口実として、「サーバー側で現在時刻を取得して、ブラウザ側でそれを端末のタイムゾーンに基づいて表示する」という、Client Component 抜きでは実装しづらい機能を実装しています。

ISO: 2025-09-25T08:15:34.840Z ブラウザ側タイムゾーンでの時刻: Thursday, September 25, 2025 at 1:15:34 AM PDT
実際の画面の様子: 世界協定時の時刻と、PDT（ブラウザ側のタイムゾーンであるサンフランシスコの現地時刻）が表示されている

▼コンポーネント間でデータが受け渡される様子の概略図

(抜粋) src/app/rsc-date/date/page.tsx

// import 一部省略
import { LocaleAwareDate } from "./locale-aware-date";
// 中略
export default async function Page({}: PageProps<"/rsc-date/date">) {
  await connection();

  return (
    <div className={styles.container}>
      {/* 中略 */}
      <section>
        <h2>アクセスした時刻:</h2>
        <LocaleAwareDate value={new Date()} />
      </section>
    </div>
  );
};

(抜粋) src/app/rsc-date/date/locale-aware-date.tsx

"use client";

// import 省略
/** ブラウザ側のタイムゾーンでの日時を表示する */
const formatter = new Intl.DateTimeFormat(undefined, {
  /* 中略 */
});

type Props = {
  value: Date;
};

export function LocaleAwareDate({ value }: Props) {
  // SSR 時: undefined
  // CSR 時には、ブラウザ側のロケールで表示
  const localDate = useSyncExternalStore(
    () => () => {},
    () => formatter.format(value),
    () => undefined
  );
  return (
    <div className={styles.root}>
      {/* 中略 */}
      <div>
        <span className={styles.prefix}>ブラウザ側タイムゾーンでの時刻: </span>
        <span className={styles.time}>{localDate}</span>
      </div>
    </div>
  );
}

ソースコード全文

src/app/rsc-date/date/page.tsx

import { type Metadata } from "next";
import { connection } from "next/server";
import Link from "next/link";

import { LocaleAwareDate } from "./locale-aware-date";
import styles from "./page.module.scss";

export const metadata: Metadata = {
  title: "Date の振る舞いテスト",
};

export default async function Page({}: PageProps<"/rsc-date/date">) {
  await connection();

  return (
    <div className={styles.container}>
      <nav className={styles.nav}>
        <Link href="/rsc-date" className={styles.navLink}>
          ← Back to RSC Date Examples
        </Link>
      </nav>
      <h1>現地時刻の振る舞いテスト</h1>
      <section>
        <h2>アクセスした時刻:</h2>
        <LocaleAwareDate value={new Date()} />
      </section>
    </div>
  );
}

src/app/rsc-date/date/locale-aware-date.tsx

"use client";

import { useSyncExternalStore } from "react";

import styles from "./locale-aware-date.module.scss";

/**
 * ブラウザ側のタイムゾーンでの日時を表示する
 */
const formatter = new Intl.DateTimeFormat(undefined, {
  weekday: "long",
  year: "numeric",
  month: "long",
  day: "numeric",
  hour: "numeric",
  minute: "numeric",
  second: "numeric",
  timeZoneName: "short",
});

type Props = {
  value: Date;
};

export function LocaleAwareDate({ value }: Props) {
  // SSR 時: undefined
  // CSR 時には、ブラウザ側のロケールで表示
  const localDate = useSyncExternalStore(
    () => () => {},
    () => formatter.format(value),
    () => undefined
  );
  // 下は Hydration Error になるのでダメ！
  // const localDate = formatter.format(value);
  return (
    <div className={styles.root}>
      <div>
        <span className={styles.prefix}>ISO: </span>
        <time className={styles.time}>{value.toISOString()}</time>
      </div>
      <div>
        <span className={styles.prefix}>ブラウザ側タイムゾーンでの時刻: </span>
        <span className={styles.time}>{localDate}</span>
      </div>
    </div>
  );
}

Zod Codecs と組み合わせれば Temporal も送れる

Temporal の日付オブジェクトはどうでしょうか？ここでは Temporal.PlainDateTime 型で試してみましょう。

（少なくとも）2025/09/24 現在では、 'use client' でシリアライズ可能なリストに列挙されておらず、そのままでは送信できません。

無理やり渡そうとすると、このようなエラーが表示されます。

（page.tsx は Server Component で、ShowPlainDateTime コンポーネントには 'use client' ディレクティブを設定しています。）

Only plain objects can be passed to Client Components from Server Components. Temporal.PlainDateTime objects are not supported.

しかし、これで終わりではありません。

シリアライズ可能なデータに変換して送信する

Server Component 側では、《'use client' でシリアライズ可能なデータ型》に変換して、Props に渡す。
- エンコード（encode）
Client Component 側では、それを受け取って、元の型に復元する
- デコード（decode）

という少しの手間を掛けさえすれば、とりあえず対応できます。

とりあえずこれで目的は果たせますが、しかし、実装するとなると、なんかゴチャッとして使いにくいユーティリティーになる匂いがします。

JavaScript/TypeScript は名前空間機能がなく、関数の名前は長〜〜い動詞句になってしまい、いろいろな情報を提供しようとすると、それぞれバラバラな名前になってしまうので、こんな感じになってしまいます。

// Server Component 側: PlainDateTime -> string
import { encodeFromPlainDateTime } from "#/utils/react/codecs/plain-date-time";
// Client Component 側: string -> PlainDateTime
import { decodeIntoPlainDateTime } from "#/utils/react/codecs/plain-date-time";

// 型の情報を SSoT （信頼できる唯一の情報源）として提供したい
import {
  type PlainDateTime,
  type PlainDateTimeUnderlying, // つまり string
} from "#/utils/react/codecs/plain-date-time";

VSCode の画面。plainDateTime と入力したところ、ShowPlainDateTime, SharablePlainDatTime, decodeToPlainDateTime, encodeFromPlainDateTime の 4つをimport 補完の候補として見せてくれている。
import 自動補完が全く役に立たない訳ではないが…

「動詞が最初に来て、その後に目的語が来る」このパターンは、UI デザインの文脈では「タスク指向 UI」、つまりユーザーに「作る側の都合」を押し付ける、悪い UI の設計とされるでしょう。

（対義語は「オブジェクト指向 UI」（OOUI）で、作り手の都合を廃して、ユーザーの脳内のイメージに合わせて作る、理想的な設計を指しています。）

ユーティリティ関数のたぐいも、実装者である同僚 etc. をユーザーと考えると一種の UI なので、「よい UI」を目指せるなら目指したいですよね？

 最悪なのは 〇〇To▲▲ / ▲▲To〇〇
plainDateTimeToString() / stringToPlainDateTime じゃだめなの？
という疑問もあるかと思います。
僕の意見としては、悪いとまでは言わないが、少し劣っていると思います。 このような名前は目的不在で、手段だけが露出しているからです。
目的:「PlainDateTime を Server -> Client でなるべくシームレスに共有して使いたい」
手段:「PlainDateTime を string に変換する」（および、その逆方向の変換）
もちろん、手段が大事な場面もありますが、今回のユーティリティは、目的駆動で設計・実装したものなので、名前もそれに追従して「目的」ベースにします。
（もちろん、内部で手段に基づいた名前のユーティリティがあっても良いですが、「表に出す/内部的にとどめる」のようなメリハリが必要です。メリハリがない utils は、どこにどの機能があるのか探しづらく、ユーザーに混乱をもたらします。）

SSoT オブジェクトに全てを集約する

では OOUI 的にするために、1つのオブジェクトに情報を集約して、その SSoT（信頼できる唯一の情報源）から情報を引き出すためのユーティリティと組み合わせて利用できるようにしてみましょう。

（ツリーシェイキングは犠牲になりますが、それほど大きなコード量にはならないので妥協することにします。）

utils/react/codecs/_codec

export type Codec<in out S, in out U> = {
  decode: (u: U) => S;
  encode: (s: S) => U;
};

export type ShapedType<C> = C extends Codec<infer S, infer _> ? S : never;
export type UnderlyingType<C> = C extends Codec<infer _, infer U>
  ? U
  : never;

utils/react/sharable/plain-date-time

import { Temporal } from "temporal-polyfill";
import type { Codec } from "./_codec";

export const SharablePlainDateTime: Codec<Temporal.PlainDateTime, string> = {
  decode: (string) => Temporal.PlainDateTime.from(string),
  encode: (dateTime) => dateTime.toString(),
}

import { type ShapedType, type UnderlyingType } "#/utils/react/sharable";
import { SharablePlainDateTime } from "#/utils/react/sharable/plain-date-time";

// Server Component 側: PlainDateTime -> string
SharablePlainDateTime.encode(plainDateTime);
// Client Component 側: string -> PlainDateTime
SharablePlainDateTime.decode(underlying);

// sharable ユーティリティを使って、SSoT としての Codec オブジェクトから型情報を抽出できる
type Props = {
  now: UnderlyingType<typeof SharablePlainDateTime>,
};
type PlainDateTime = ShapedType<typeof SharablePlainDateTime>;

こうすれば、

エンコード関数
デコード関数
Shaped 型の情報
Underlying 型の情報

が全て、SSoT たる PlainDateTimeCodec オブジェクトから派生的に得られるようになっています。これはかなり OOUI 的でわかりやすいと思います。

"#/utils/react/sharable" ユーティリティの使い方をユーザーが知っておく必要があるのは不便に思われるかもしれませんが、情報がうまく集約されたことと比べれば、必要な学習コストだと割り切っても良いでしょう。

Zod Codecs のパターンに乗っかる

上記では、お手製の Codec ユーティリティを使って、シリアライゼーションのための双方向の型変換にパターンを規定してあげて、取り扱いを容易にしました。

しかし、実は、このパターンを提供してくれるようになったライブラリがあります。

それが Zod です。

Zod は v4.1 から、Codecs という双方向の型変換をサポートする仕組みを提供しています。（従来のスキーマは、単一方向の型変換のみサポートしていました。）

https://zod.dev/codecs

この Codec の仕組みは、そのまま今回のユーティリティに採用できます。

 既存のライブラリを使うメリットCodec ユーティリティは、「ユーティリティのためのユーティリティ」と言えるような存在です。#/utils/react/sharable/plain-date-time のような、個々の《具体的なユーティリティ》に制約を加えて、その品質を安定させる働きがあります。
「ユーティリティ」とは、アプリケーションのコードの中に繰り返し登場して、1つの部品として成り立つようなカタマリを取り出しててできるモノです。
筋の良いユーティリティは、コード全体の統一感や、ひいては品質の安定に繋がります。
しかし、ユーティリティの設計がヘタクソだと、
逆に、ユーザー側のボイラープレートが増える
異常系を握りつぶしてしまい、型情報から消えてしまい。ユーザー側からは分かりづらい
ということに繋がり、かえってアプリケーションの品質の低下に繋がります。
であれば、 「ユーティリティのためのユーティリティ」の筋が悪いと、コード全体への悪影響は、もっと大きいものになる ことは明らかです。
ライブラリを使おうという話題になると「ロックインしたくない〜」と紋切り型の反発コメントが目につきますが、
「設計力の低い人がユーティリティ or ユーティリティを自作しようとして、切り出し方を間違って筋の悪いのを作り込んでしまい、ソースコードがめちゃくちゃになる」という損失を考えたら、既存のライブラリの使える機能を見つけて、それを使うほうが確実だと思います。
どうしても心配なら、Codec を自作したように、設計意図だけをパクって自前の内部的なユーティリティとして実装しなおしても良いです。

アクセス時のサーバー内部の現在時刻フォーマット済み: 2025年9月25日 17:15:43
完成品。ブラウザ側のタイムゾーン（「サンフランシスコ」に設定されている）に左右されず、アクセス時のサーバー内部（JST）の現在時刻を表示できている。

ISO: 2025-09-25T08:15:34.840Z ブラウザ側タイムゾーンでの時刻: Thursday, September 25, 2025 at 1:15:34 AM PDT
比較用: Date の例では、世界協定時の時刻と、PDT（ブラウザ側のタイムゾーンであるサンフランシスコの現地時刻）を表示していた

ソースコード

以下に、ソースコードの配置およびその本文を示します。（CSS Module ファイルについては、省略）

src/app/rsc-date/temporal/
├── _utils/
│   └── share-value-by-codec.ts        # Codec ユーティリティ
├── _sharable-plain-date-time.ts       # Zod Codec の定義
├── page.tsx                           # ページコンポーネント（Server）
├── page.module.scss                   # 同コンポーネントのスタイル
├── show-plain-date-time.tsx           # 日付表示コンポーネント（`'use client'` あり）
└── show-plain-date-time.module.scss   # 同コンポーネントのスタイル

src/app/rsc-date/temporal/_utils/share-value-by-codec.ts

import * as z from "zod/mini";

/**
 * - encode: Shaped -> Underlying
 * - decode: Underlying -> Shaped
 *
 * - Shaped: サーバー <-> クライアント 間で共有したいが、直列化が不可能なデータ型
 * - Underlying: "use client" で直列化可能なデータ型
 */
export { codec } from "zod/mini";
export { encode, decode } from "zod/mini";

export type UnderlyingType<T> = z.input<T>;
export type ShapedType<T> = z.output<T>;

src/app/rsc-date/temporal/_sharable-plain-date-time.ts

import { z } from "zod/mini";
import { Temporal } from "temporal-polyfill";
import { codec } from "./_utils/share-value-by-codec";

/**
 * - 表面的に利用可能な型: PlainDateTime
 * - "use client" で直列化するあめの型: string
 */
export const SharablePlainDateTime = codec(
  z.string(),
  z.instanceof(Temporal.PlainDateTime),
  {
    decode: (string) => Temporal.PlainDateTime.from(string),
    encode: (dateTime) => dateTime.toString(),
  }
);

src/app/rsc-date/temporal/page.tsx

import { Temporal } from "temporal-polyfill";
import { type Metadata } from "next";
import { connection } from "next/server";
import Link from "next/link";

import { ShowPlainDateTime } from "./show-plain-date-time";
import { SharablePlainDateTime } from "./_sharable-plain-date-time";
import { encode } from "./_utils/share-value-by-codec";
import styles from "./page.module.scss";

export const metadata: Metadata = {
  title: "Temporal.PlainDateTime の振る舞いテスト",
};

export default async function Page({}: PageProps<"/rsc-date/temporal">) {
  await connection();
  const nowPlain = Temporal.Now.plainDateTimeISO();

  return (
    <div className={styles.container}>
      <nav className={styles.nav}>
        <Link href="/rsc-date" className={styles.navLink}>
          ← Back to RSC Date Examples
        </Link>
      </nav>
      <h1>Temporal.PlainDateTime の振る舞いテスト</h1>
      <h2>アクセス時のサーバー内部の現在時刻</h2>
      <div className={styles.cluster}>
        <ShowPlainDateTime
          nowPlainDateTime={encode(SharablePlainDateTime, nowPlain)}
        />
      </div>
    </div>
  );
}

src/app/rsc-date/temporal/show-plain-date-time.tsx

"use client";

import { SharablePlainDateTime } from "./_sharable-plain-date-time";
import {
  decode,
  type ShapedType,
  type UnderlyingType,
} from "./_utils/share-value-by-codec";

import styles from "./show-plain-date-time.module.scss";

type Props = {
  nowPlainDateTime: UnderlyingType<typeof SharablePlainDateTime>;
};

export function ShowPlainDateTime({
  nowPlainDateTime: _nowPlainDateTime,
}: Props) {
  const nowPlainDateTime = decode(SharablePlainDateTime, _nowPlainDateTime);

  return (
    <div className={styles.card}>
      <span>フォーマット済み: </span>
      <span>{formatDateTime(nowPlainDateTime)}</span>
    </div>
  );
}

const formatDateTime = (d: ShapedType<typeof SharablePlainDateTime>) => {
  const year = d.year;
  const month = d.month;
  const day = d.day;
  const hour = d.hour.toString().padStart(2, "0");
  const minute = d.minute.toString().padStart(2, "0");
  const second = d.second.toString().padStart(2, "0");
  return `${year}年${month}月${day}日 ${hour}:${minute}:${second}`;
};

他にもいろいろな Codec があるよ

Zod の Codec としては、他にもいろいろなモノがあります。

先述の通り、'use client' は Date とかもサポートしているので、Codec が必要になるケースは多くないと思いますが、URL を string にシリアライズする codec なんかは 'use client' と合わせて使えるかもしれません。

Codec、面白そうなので、必要な場面があれば使ってみたいところですね！

まとめ

'use client' でのシリアライズ処理においては、Date など、JSON よりも広い範囲のデータがサポートされており、RSC の「サーバー側 / ブラウザ側のコードをシームレスに繋ぎ合わせる」というコンセプト を体現しています。

Temporal の各型のように、サポートされていないデータ型もありますが、Zod の Codecs 機能 を使えば、わずかなボイラープレートだけで「シリアライズ可能な形に変換 / そこからもとに戻す」処理を追記できるようになり、ある程度の「シームレスさ」をキープできます。

もっと広い視点でみると、Zod や Valibot のようなスキーマライブラリは、単なるフォームやJSONオブジェクトの検証だけでなく、「Opaque Type のように、単一の値をラップする」みたいな使い方まで可能だと考えています。

いわゆる "Parse, don't validate" 原則に従って運用することよって、生の TS の型チェックよりも強力な「静的なチェック」を導入して、実行時エラーの発生しうる範囲を限定することによって、ソースコードを読みやすくする力があると考えています。

Codecs に限らず、スキーマライブラリのポテンシャルが最大限に活用され、世界中のコードがもっと堅牢になることを願って、この記事を締めくくります。

株式会社ゆめみPublication

みんな知ってるあのサービスも、ゆめみが一緒に作ってます。スマホアプリ/Webサービスの企画・UX/UI設計、開発運用の内製化支援。Swift,Kotlin,Rust,Go,Flutter,ML,React,AWS等エンジニア・クリエイターの会社です。Twitterで情報配信中

Zod Codecs で 'use client' を介した Server-Client 間データ転送を強化する

`'use client'` だけで Date を送れる

Zod Codecs と組み合わせれば Temporal も送れる

シリアライズ可能なデータに変換して送信する

SSoT オブジェクトに全てを集約する

Zod Codecs のパターンに乗っかる

ソースコード

他にもいろいろな Codec があるよ

まとめ

関連記事

Discussion

'use client' だけで Date を送れる

Zod Codecs と組み合わせれば Temporal も送れる

シリアライズ可能なデータに変換して送信する

SSoT オブジェクトに全てを集約する

Zod Codecs のパターンに乗っかる

ソースコード

他にもいろいろな Codec があるよ

まとめ

関連記事

Discussion

`'use client'` だけで Date を送れる