TanStack StartをLambda Web Adapterでデプロイしてみた

2025.12.09
TanStack StartをLambda Web Adapterでデプロイしてみた
この記事をシェアする

TanStack StartをAWS Lambda Web Adapterで動かしてみました。
Next.jsの代替として注目されているTanStack Startですが、この記事では、AWS Lambdaで動かすための、設定や手順を紹介します。

1. この記事の要約

  • TanStack Startアプリを、コード変更なしでAWS Lambdaで動作させるデモを作成
  • AWS Lambda Web Adapter(LWA)を使用し、Dockerイメージでデプロイ
  • アーキテクチャはCloudFront + Function URLの構成を採用
  • ベースイメージはセキュリティと軽量化を重視してDistrolessを選択
  • Streaming SSRは検証の難易度と時間の都合により今後の課題とした
  • デモコードはGitHubリポジトリで公開

https://github.com/s4k4x4r0/tanstack-start-lambda-demo

2. TanStack Startとは?

TanStack Startは、TanStack Routerをベースに構築されたReact向けのフルスタックフレームワークです。
Next.jsのようなファイルベースルーティングやServer Functions(RPC)を備えつつ、クライアントサイド(SPA)の挙動を主軸に置いた設計が特徴です。

2024年11月頃、SNS等で「TanStack Startを試してみたけど、もうNext.jsには戻れない」という議論が話題になり、完全な型安全性、Viteの爆速開発体験、明示的な設計と言われています。

https://zenn.dev/yt4/articles/tanstack-start-next-js

3. AWS Lambda Web Adapterとは?

AWS Lambda Web Adapter(LWA)は、任意のウェブアプリケーションをコード変更なしでAWS Lambda上で動作させるためのツールです。
Lambda ExtensionとしてデプロイされるLWAは、LambdaへのイベントをHTTPリクエストに変換し、ローカルホストで待機しているウェブアプリに転送します。

詳しい解説は以下の記事が参考になります。

https://speakerdeck.com/tmokmssaws-lambda-web-adapterwohuo-yong-suruxin-siisabaresunoshi-zhuang-patan

4. アーキテクチャの選択

TanStack StartをLambdaで動かすにあたり、以下の構成パターンを検討しました。

4-1. AWSリソース構成

構成特徴採用可否
CloudFront + Function URL構成がシンプル。レスポンスストリーミング対応。採用
API Gateway + Lambda高機能だが設定が複雑。コストが比較的高め。不採用

将来的なストリーミング対応を見越してFunction URLを採用しました。

注意: CloudFront + Lambda Function URLでIAM認証を使用する場合、コンテンツハッシュを計算する処理の実装が必須です。
これを実装しないと、TanStack Startで作成したアプリは正常に動作しません。
詳細は以下の記事を参照してください。

https://dev.classmethod.jp/articlescloudfront-lambda-url-with-post-put-request/

4-2. Lambdaパッケージ方式

方式特徴採用可否
Docker イメージ依存関係(OSライブラリ等)の管理が楽。移植性が高い。採用
Zip アーカイブビルドが高速な場合がある。サイズ制限(250MB)が厳しい。不採用

ZipとDockerイメージでコールドスタート性能に大きな差はないという検証結果もあります。

https://note.com/kind_ixia1/n/n10ee12d0856b

今回は環境構築の確実性を優先してDockerイメージを採用しました。

4-3. ベースイメージの選定

LambdaでコンテナイメージをデプロイすぐときLambdaでコンテナを動かす場合、通常はAWS公式のLambda専用ベースイメージ(RIC入り)が推奨されます。
しかし、LWAを使う場合は事情が異なります。

  • AWS公式Lambdaイメージ: Lambda Runtime Interface Client(RIC)が含まれており、LWAと役割が重複・競合する可能性がある
  • 汎用イメージ(Distroless / Node-slim): LWAがLambda APIとの通信を担当するため、アプリ側は普通のLinux環境で動けばよい

そのため、LWAを使う場合はDistrolessやAlpine/Slimなどの汎用的な軽量イメージを使うのがベストプラクティスとなります。
今回はセキュリティとサイズ削減のためDistrolessを採用しました。

5. 実装例

作成したデモコードは以下のリポジトリで公開しています。

https://github.com/s4k4x4r0/tanstack-start-lambda-demo

  • 技術スタック: TanStack Start、AWS Lambda Web Adapter、AWS CDK、Docker、pnpm(Monorepo)

CDKでAWSリソースを定義していますので、簡単にデプロイができます。

動作イメージ

初期ページ、および、ボタンを押した時のリクエスト、全てがLambdaで処理されます。

5-1. ディレクトリ構成

pnpm workspaceを使用したモノレポ構成を採用しました。

.
├── Dockerfile                  # アプリのコンテナイメージビルド用(ルート配置)
├── package.json                # ルート設定・スクリプト
├── pnpm-workspace.yaml         # ワークスペース定義
└── packages
    ├── app                     # TanStack Start アプリケーション
    │   ├── vite.config.ts      # アプリ設定 (Vite/TanStack Start/Nitro)
    │   ├── package.json
    │   └── src/                # ソースコード (TanStack Start 標準構成)
    │       ├── routes/
    │       └── router.tsx
    └── infra                   # AWS CDK コード
        ├── lib/
        ├── bin/
        └── package.json

6. 実装のポイント

6-1. vite.config.ts

Viteの設定です。
TanStack Startのプラグインの他に、Nitroプラグインが必要です。
Nitroがサーバービルドの出力を制御します。

// packages/app/vite.config.ts
import { tanstackStart } from "@tanstack/react-start/plugin/vite";
import viteReact from "@vitejs/plugin-react-swc";
import { nitro } from "nitro/vite";
import { defineConfig } from "vite";
import tsConfigPaths from "vite-tsconfig-paths";

export default defineConfig({
  server: {
    port: 3000,
  },
  plugins: [
    tsConfigPaths(),
    tanstackStart(),
    nitro(), // Nitro統合
    viteReact(),
  ],
  nitro: {},
});

6-2. Dockerfile

LWAの肝となる設定です。

ポイントは、本番イメージでCOPY --from=public.ecr.aws/awsguru/aws-lambda-adapter:0.9.1 /lambda-adapter /opt/extensions/lambda-adapterを実行して、LWAをextensionとして追加することです。
これだけで、LWAが稼働し始めます。手軽ですね。

環境変数PORTを指定して、LWAとNitroの両方に使用するポート番号を通知します。
やらないと、Nitroが待つポートと、LWAが転送するポートが一致しなくて動きません。

なお、今回はマルチステージビルド + Distrolessイメージの使用で、軽量かつセキュアなイメージを作成しています。

# --- Build Stage ---
FROM public.ecr.aws/docker/library/node:24-slim AS build
ENV PNPM_HOME="/pnpm"
ENV PATH="$PNPM_HOME:$PATH"
RUN corepack enable

WORKDIR /usr/src/project
COPY pnpm-lock.yaml ./
# pnpm fetch でストアのみ先に取得(キャッシュ効率向上)
RUN --mount=type=cache,id=pnpm,target=/pnpm/store pnpm fetch
COPY . ./
# 依存関係インストールとビルド
RUN --mount=type=cache,id=pnpm,target=/pnpm/store pnpm install --frozen-lockfile --offline --ignore-scripts
RUN pnpm run -r build
# 必要なパッケージ(app)のみをプロダクション用に抽出
RUN pnpm deploy --filter=app --prod /prod/app

# --- Runtime Stage ---
FROM gcr.io/distroless/nodejs24-debian13:latest AS app

# AWS Lambda Web Adapter を extension としてコピー
COPY --from=public.ecr.aws/awsguru/aws-lambda-adapter:0.9.1 /lambda-adapter /opt/extensions/lambda-adapter

WORKDIR /prod/app
# ビルド済みのアプリケーション一式をコピー
COPY --from=build --chown=nonroot:nonroot /prod/app ./

USER nonroot
ENV NODE_ENV=production PORT=3000
EXPOSE 3000

# TanStack Start (Nitro) のビルド成果物を実行
CMD [ ".output/server/index.mjs" ]

6-3. .dockerignore

Dockerビルド時に不要なファイルを除外するため、.dockerignoreを設定します。
特に重要なのは、packages/infraディレクトリをビルドコンテキストから除外することです。

# ... 省略 ...
packages/infra

infraパッケージをビルドに含めてしまうと、CDK実行時に依存関係の不整合でエラーが発生する可能性があります。

6-4. CDKスタック定義(CloudFront + Function URL)

CloudFront + Function URLの構成を定義します。

// packages/infra/lib/tan-stack-lambda-demo-stack.ts(抜粋)
import * as cdk from "aws-cdk-lib";
import * as cloudfront from "aws-cdk-lib/aws-cloudfront";
import * as origins from "aws-cdk-lib/aws-cloudfront-origins";
import * as lambda from "aws-cdk-lib/aws-lambda";

// Lambdaコンテナ関数の作成
const handler = new lambda.DockerImageFunction(this, "Handler", {
  code: lambda.DockerImageCode.fromImageAsset(
    path.join(__dirname, "../../../"),
  ),
  memorySize: 128,
  timeout: cdk.Duration.seconds(5),
  architecture: lambda.Architecture.ARM_64,
  environment: {
    AWS_LWA_INVOKE_MODE: "response_stream",
  },
});

// Function URLの作成(IAM認証 + ストリーミングモード)
const fnUrl = handler.addFunctionUrl({
  authType: lambda.FunctionUrlAuthType.AWS_IAM,
  invokeMode: lambda.InvokeMode.RESPONSE_STREAM,
});

// CloudFrontディストリビューションの作成
new cloudfront.Distribution(this, "Distribution", {
  defaultBehavior: {
    origin: origins.FunctionUrlOrigin.withOriginAccessControl(fnUrl),
    allowedMethods: cloudfront.AllowedMethods.ALLOW_ALL,
    viewerProtocolPolicy: cloudfront.ViewerProtocolPolicy.REDIRECT_TO_HTTPS,
    originRequestPolicy:
      cloudfront.OriginRequestPolicy.ALL_VIEWER_EXCEPT_HOST_HEADER,
    cachePolicy: cloudfront.CachePolicy.CACHING_DISABLED,
    edgeLambdas: [
      {
        functionVersion: props.edgeFunction.currentVersion,
        eventType: cloudfront.LambdaEdgeEventType.ORIGIN_REQUEST,
        includeBody: true,
      },
    ],
  },
});

このスタック定義のポイントは以下の通りです。

  • Origin Access Control: withOriginAccessControl(fnUrl)で、Lambdaを呼び出せるリソースをCloudFrontに限定できます。
  • Lambda@Edge: ORIGIN_REQUESTイベントでコンテンツハッシュを計算(POST/PUTリクエストに必須)
  • 全HTTPメソッド許可: ALLOW_ALLでGET/POST/PUT等すべてのメソッドに対応
  • originRequestPolicy: ALL_VIEWER_EXCEPT_HOST_HEADER。

下の2つはTanStack Startを正常に動作させる上で重要です。
使用するメソッドやクエリパラメータなどは、Webフレームワーク側で隠蔽されているので、基本的に全部通すのが良いです。

あと、キャッシュポリシーについては今回はキャッシュしない設定にしていますが、適切にキャッシュするのが良いと思われます。

7. 今後の課題

7-1. Streaming SSRの実現

今回は初期表示の安定性を優先しましたが、TanStack Startの真価であるStreaming SSRをLambda上で実現するには、以下の検証が必要です。

  • LWAのInvoke Mode: response_streamを有効化した際の挙動確認
  • レスポンスヘッダ: Transfer-Encoding: chunkedが正しくLambdaからクライアントまで(CloudFront/Function URL経由で)届くか
  • React Suspense: サーバー側でのサスペンドとストリーム送出が期待通りに行われるか

これらの検証は別の機会に実施する予定です。

さいごに

本記事では、TanStack StartをAWS Lambda Web Adapterで動かすデモプロジェクトを作成しました。
実際に試してみて、以下のような所感を得ました。

  • LWAの手軽さは健在で、アプリケーションコード側をほとんど変更せず、DockerfileにLWAを追加するだけでLambdaで動くのは非常に強力だった
  • TanStack Startはまだ新しいフレームワークのため、ビルド成果物の構造やデプロイ先のプリセット設定には試行錯誤が必要だった
  • Function URLは検証用としてはALBやAPI Gatewayを立てずに済むため、コスト・手間の面で最適だった

今後はStreaming SSRの実現に挑戦し、TanStack Startの真価をサーバーレス環境で引き出せるか検証していきたいと考えています。

この記事をシェアする
著者:酒井亮太郎
シナモロール