セッション

追加： astro@5.7.0

セッションは、オンデマンドレンダリングされるページ間でリクエストをまたいでデータを共有するために使用します。

cookiesとは異なり、セッションはサーバーに保存されるため、サイズ制限やセキュリティの問題を気にすることなく大量のデータを保存できます。ユーザーデータ、ショッピングカート、フォームの状態などの保存に便利で、クライアントサイドのJavaScriptなしで動作します。

src/components/CartButton.astro

---
export const prerender = false; // 'server' outputでは不要
const cart = await Astro.session?.get('cart');
---

<a href="/checkout">🛒 {cart?.length ?? 0} items</a>

セッションの設定

セッションを使うには、セッションデータを保存するためのストレージドライバーが必要です。Node、Cloudflare (EN)、Netlifyのアダプターはデフォルトのドライバーを自動的に設定しますが、その他のアダプターでは現在ドライバーを手動で指定 (EN)する必要があります。

astro.config.mjs

  {
    adapter: vercel(),
    session: {
      driver: "redis",
    },
  }

ストレージドライバーの設定やその他の設定可能なオプションの詳細については、session設定オプション (EN)を参照してください。

セッションデータの操作

sessionオブジェクト (EN)を使用すれば、保存されたユーザー状態の操作（例: ショッピングカートへのアイテム追加）やセッションIDの操作（例: ログアウト時のセッションIDクッキーの削除）が可能です。このオブジェクトは、AstroコンポーネントやページではAstro.sessionから、APIエンドポイント、ミドルウェア、アクションではcontext.sessionからアクセスできます。

セッションは初回使用時に自動的に生成され、session.regenerate() (EN)でいつでも再生成したり、session.destroy() (EN)で破棄したりできます。

多くのユースケースでは、session.get() (EN)とsession.set() (EN)のみで十分です。

詳細については、セッションAPIリファレンス (EN)を参照してください。

Astroコンポーネントとページ

.astroコンポーネントやページでは、グローバルなAstroオブジェクトを通じてセッションオブジェクトにアクセスできます。たとえば、ショッピングカート内のアイテム数を表示するには次のようにします。

src/components/CartButton.astro

---
export const prerender = false; // 'server' outputでは不要
const cart = await Astro.session?.get('cart');
---

<a href="/checkout">🛒 {cart?.length ?? 0} items</a>

APIエンドポイント

APIエンドポイントでは、contextオブジェクトからセッションオブジェクトにアクセスできます。たとえば、ショッピングカートにアイテムを追加するには次のようにします。

src/pages/api/addToCart.ts

export async function POST(context: APIContext) {
  const cart = await context.session?.get('cart') || [];
  const data = await context.request.json<{ item: string }>();
  if(!data?.item) {
    return new Response('Item is required', { status: 400 });
  }
  cart.push(data.item);
  await context.session?.set('cart', cart);
  return Response.json(cart);
}

アクション

アクションでは、contextオブジェクトからセッションオブジェクトにアクセスできます。たとえば、ショッピングカートにアイテムを追加するには次のようにします。

src/actions/addToCart.ts

import { defineAction } from 'astro:actions';
import { z } from 'astro/zod';

export const server = {
  addToCart: defineAction({
    input: z.object({ productId: z.string() }),
    handler: async (input, context) => {
      const cart = await context.session?.get('cart');
      cart.push(input.productId);
      await context.session?.set('cart', cart);
      return cart;
    },
  }),
};

ミドルウェア

ノート

エッジミドルウェアではセッションはサポートされていません。

ミドルウェアでは、contextオブジェクトからセッションオブジェクトにアクセスできます。たとえば、セッションに最終訪問日時を設定するには次のようにします。

src/middleware.ts

import { defineMiddleware } from 'astro:middleware';

export const onRequest = defineMiddleware(async (context, next) => {
  context.session?.set('lastVisit', new Date());
  return next();
});

セッションデータの型

デフォルトではセッションデータには型がなく、任意のキーに任意のデータを保存できます。値はdevalueを使用してシリアライズ・デシリアライズされます。これはコンテンツコレクションやアクションで使用されているのと同じライブラリです。そのため、サポートされる型も同じで、文字列、数値、Date、Map、Set、URL、配列、プレーンなオブジェクトが含まれます。

src/env.d.tsファイルを作成し、App.SessionData型の宣言を追加することで、セッションデータのTypeScript型を定義 (EN)することもできます。

src/env.d.ts

declare namespace App {
  interface SessionData {
    user: {
      id: string;
      name: string;
    };
    cart: string[];
  }
}

これにより、エディターで型チェックと自動補完を使ってセッションデータにアクセスできるようになります。

src/components/CartButton.astro

---
const cart = await Astro.session?.get('cart');
// const cart: string[] | undefined

const something = await Astro.session?.get('something');
// const something: any

Astro.session?.set('user', { id: 1, name: 'Houston' });
// Error: Argument of type '{ id: number; name: string }' is not assignable to parameter of type '{ id: string; name: string; }'.
---

注意

これは型チェックにのみ使用され、セッションのランタイムの動作には影響しません。ユーザーがセッションにデータを保存した状態で型を変更すると、ランタイムエラーが発生する可能性があるため、十分に注意してください。