elysiajs

ElysiaJS 開発スキル

コード例と最新の API については、必ず elysiajs.com/llms.txt を参照してください。

概要

ElysiaJS は、Bun を第一の対象としながらも Bun に限定されない、型安全で高性能なバックエンドサーバーを構築するための TypeScript フレームワークです。このスキルでは、ルーティング、バリデーション、認証、プラグイン、統合、デプロイなど、Elysia を使った開発に関する包括的なガイダンスを提供します。

このスキルを使用するタイミング

ユーザーから次の依頼があった場合に、このスキルを使用します。

• ElysiaJS のルート、ハンドラー、サーバーを作成または変更する
• TypeBox やその他のスキーマライブラリ（Zod、Valibot）を使ってバリデーションを設定する
• 認証（JWT、セッションベース、マクロ、ガード）を実装する
• プラグイン（CORS、OpenAPI、静的ファイル、JWT）を追加する
• 外部サービス（Drizzle ORM、Better Auth、Next.js、Eden Treaty）と統合する
• リアルタイム機能向けの WebSocket エンドポイントを設定する
• Elysia インスタンスの単体テストを作成する
• Elysia サーバーを本番環境にデプロイする

クイックスタート

クイックスキャフォールド：

bun create elysia app

基本的なサーバー

import { Elysia, t, status } from 'elysia'

const app = new Elysia()
  	.get('/', () => 'Hello World')
   	.post('/user', ({ body }) => body, {
    	body: t.Object({
      		name: t.String(),
        	age: t.Number()
     	})
    })
    .get('/id/:id', ({ params: { id } }) => {
   		if(id > 1_000_000) return status(404, 'Not Found')
     
     	return id
    }, {
    	params: t.Object({
     		id: t.Number({
       			minimum: 1
       		})
     	}),
     	response: {
      		200: t.Number(),
        	404: t.Literal('Not Found')
      	}
    })
    .listen(3000)

基本的な使い方

HTTP メソッド

import { Elysia } from 'elysia'

new Elysia()
  .get('/', 'GET')
  .post('/', 'POST')
  .put('/', 'PUT')
  .patch('/', 'PATCH')
  .delete('/', 'DELETE')
  .options('/', 'OPTIONS')
  .head('/', 'HEAD')

パスパラメーター

.get('/user/:id', ({ params: { id } }) => id)
.get('/post/:id/:slug', ({ params }) => params)

クエリパラメーター

.get('/search', ({ query }) => query.q)
// GET /search?q=elysia → "elysia"

リクエストボディ

.post('/user', ({ body }) => body)

ヘッダー

.get('/', ({ headers }) => headers.authorization)

TypeBox によるバリデーション

基本的な型

import { Elysia, t } from 'elysia'

.post('/user', ({ body }) => body, {
  body: t.Object({
    name: t.String(),
    age: t.Number(),
    email: t.String({ format: 'email' }),
    website: t.Optional(t.String({ format: 'uri' }))
  })
})

ネストしたオブジェクト

body: t.Object({
  user: t.Object({
    name: t.String(),
    address: t.Object({
      street: t.String(),
      city: t.String()
    })
  })
})

配列

body: t.Object({
  tags: t.Array(t.String()),
  users: t.Array(t.Object({
    id: t.String(),
    name: t.String()
  }))
})

ファイルアップロード

.post('/upload', ({ body }) => body.file, {
  body: t.Object({
    file: t.File({
      type: 'image',              // image/* mime types
      maxSize: '5m'               // 5 megabytes
    }),
    files: t.Files({              // Multiple files
      type: ['image/png', 'image/jpeg']
    })
  })
})

レスポンスのバリデーション

.get('/user/:id', ({ params: { id } }) => ({
  id,
  name: 'John',
  email: '[email protected]'
}), {
  params: t.Object({
    id: t.Number()
  }),
  response: {
    200: t.Object({
      id: t.Number(),
      name: t.String(),
      email: t.String()
    }),
    404: t.String()
  }
})

Standard Schema（Zod、Valibot、ArkType）

Zod

import { z } from 'zod'

.post('/user', ({ body }) => body, {
  body: z.object({
    name: z.string(),
    age: z.number().min(0),
    email: z.string().email()
  })
})

エラーハンドリング

.get('/user/:id', ({ params: { id }, status }) => {
  const user = findUser(id)
  
  if (!user) {
    return status(404, 'User not found')
  }
  
  return user
})

ガード（複数のルートに適用）

.guard({
  params: t.Object({
    id: t.Number()
  })
}, app => app
  .get('/user/:id', ({ params: { id } }) => id)
  .delete('/user/:id', ({ params: { id } }) => id)
)

マクロ

.macro({
  hi: (word: string) => ({
    beforeHandle() { console.log(word) }
  })
})
.get('/', () => 'hi', { hi: 'Elysia' })

プロジェクト構成（推奨）

Elysia は特定の設計方針を押し付けませんが、ユーザーの要望に基づいて構成できます。特に希望がない場合は、各機能がコントローラー、サービス、モデルを含む独自のフォルダーを持つ、機能ベースかつドメイン駆動型のフォルダー構成を推奨します。

src/
├── index.ts              # Main server entry
├── modules/
│   ├── auth/
│   │   ├── index.ts      # Auth routes (Elysia instance)
│   │   ├── service.ts    # Business logic
│   │   └── model.ts      # TypeBox schemas/DTOs
│   └── user/
│       ├── index.ts
│       ├── service.ts
│       └── model.ts
└── plugins/
    └── custom.ts

public/                   # Static files (if using static plugin)
test/                     # Unit tests

各ファイルの責務は次のとおりです。

• コントローラー（index.ts）：HTTP ルーティング、リクエストのバリデーション、Cookie を処理します。
• サービス（service.ts）：ビジネスロジックを処理します。可能であれば Elysia コントローラーから切り離します。
• モデル（model.ts）：リクエストとレスポンスのデータ構造およびバリデーションを定義します。

ベストプラクティス

Elysia は設計パターンを指定しませんが、指定がない場合は、機能ベースのフォルダー構成と組み合わせた MVC パターンを利用できます。

• コントローラー：
  • HTTP に依存するコントローラーには、Elysia をコントローラーとして使用することを推奨します
  • HTTP に依存しない処理については、明示的に求められない限り、サービスを使用することを推奨します
  • ローカルのカスタムエラーを処理するには onError を使用します
  • Elysia.models({ ...models }) でモデルを Elysia インスタンスに登録し、モデルには Elysia.prefix('model', 'Namespace.') で名前空間のプレフィックスを付けます
  • 実際の Model.name ではなく、Elysia が提供する名前でモデルを参照することを推奨します
• サービス：
  • クラスを推奨します（可能であれば抽象クラス）
  • Model から派生させたインターフェース／型を推奨します
  • エラー時は status（import { status } from 'elysia'）を返します
  • throw Error ではなく return Error を推奨します
• モデル：
  • バリデーションモデルと、そのバリデーションモデルの型を必ずエクスポートします
  • カスタムエラーは Model に含めます

Elysia の重要な概念

Elysia を使う前に理解しておくべき重要な概念とルールがあります。

カプセル化 - デフォルトで分離

ライフサイクル（フック、ミドルウェア）は、スコープを指定しない限り、インスタンス間で漏れません。

スコープのレベル：

• local（デフォルト） - 現在のインスタンスとその子孫
• scoped - 親、現在のインスタンス、その子孫
• global - すべてのインスタンス

.onBeforeHandle(() => {}) // only local instance
.onBeforeHandle({ as: 'global' }, () => {}) // exports to all

メソッドチェーン - 型に必須

必ずチェーンしてください。各メソッドは新しい型参照を返します。

❌ しない：

const app = new Elysia()
app.state('build', 1) // loses type
app.get('/', ({ store }) => store.build) // build doesn't exists

✅ する：

new Elysia()
  .state('build', 1)
  .get('/', ({ store }) => store.build)

依存関係の明示

各インスタンスは独立しています。使用するものを宣言してください。

const auth = new Elysia()
	.decorate('Auth', Auth)
	.model(Auth.models)

new Elysia()
  .get('/', ({ Auth }) => Auth.getProfile()) // Auth doesn't exists

new Elysia()
  .use(auth) // must declare
  .get('/', ({ Auth }) => Auth.getProfile())

グローバルスコープを使用する場合：

• 型を追加しない場合（cors、helmet）
• グローバルライフサイクルの場合（ロギング、トレーシング）

明示的に宣言する場合：

• 型を追加する場合（state、models）
• ビジネスロジックの場合（auth、db）

重複排除

名前を付けない限り、プラグインは再実行されます。

new Elysia() // rerun on `.use`
new Elysia({ name: 'ip' }) // runs once across all instances

順序が重要

イベントは、登録後のルートに適用されます。

.onBeforeHandle(() => console.log('1'))
.get('/', () => 'hi') // has hook
.onBeforeHandle(() => console.log('2')) // doesn't affect '/'

型推論

正確な型を得るには、インライン関数のみを使用してください。

コントローラーでは、インラインラッパー内で分割代入します。

.post('/', ({ body }) => Controller.greet(body), {
  body: t.Object({ name: t.String() })
})

スキーマから型を取得します。

type MyType = typeof MyType.static

参照モデル

モデルは名前で参照できます。API のドキュメント作成に特に便利です。

new Elysia()
	.model({
		book: t.Object({
			name: t.String()
		})
	})
	.post('/', ({ body }) => body.name, {
		body: 'book'
	})

.prefix / .suffix を使用してモデル名を変更できます。

new Elysia()
	.model({
		book: t.Object({
			name: t.String()
		})
	})
	.prefix('model', 'Namespace')
	.post('/', ({ body }) => body.name, {
		body: 'Namespace.Book'
	})

prefix を指定すると、モデル名はデフォルトで大文字になります。

技術用語

以下は Elysia で使用される技術用語です。

• OpenAPI Type Gen - 型から OpenAPI を生成する @elysiajs/openapi の関数名 fromTypes。plugins/openapi.md を参照してください。
• Eden、Eden Treaty - バックエンドからフロントエンドへ型を共有するための、エンドツーエンドで型安全な RPC クライアント

リソース

必要に応じて、以下のリファレンスを使用してください。

最も重要な基礎構成要素が例とともに含まれているため、route.md を確認することをおすすめします。

plugin.md と validation.md も重要ですが、必要に応じて確認できます。

references/

トピックごとに分かれた詳細なドキュメント：

• bun-fullstack-dev-server.md - HMR 対応の Bun フルスタック開発サーバー。バンドラーなしで React を使用します。
• cookie.md - Cookie に関する詳細なドキュメント
• deployment.md - 本番環境へのデプロイガイド／Docker
• eden.md - バックエンドからフロントエンドへ型を共有するための、エンドツーエンドで型安全な RPC クライアント
• guard.md - バリデーション／ライフサイクルを一括設定
• macro.md - キーと値を使って複数のスキーマ／ライフサイクルを再利用可能な Elysia としてまとめます（認証、認可、ロールベースのアクセスチェックなど、複雑なセットアップにおすすめ）
• plugin.md - Elysia の一部を独立したコンポーネントに分離
• route.md - Elysia の基礎構成要素：ルーティング、ハンドラー、コンテキスト
• testing.md - 例を含む単体テスト
• validation.md - 入出力のバリデーション設定と、すべてのカスタムバリデーションルールの一覧
• websocket.md - リアルタイム機能

plugins/

公式 Elysia プラグインの詳細なドキュメント、使用方法、設定リファレンス：

• bearer.md - Elysia にベアラー機能を追加（@elysiajs/bearer）
• cors.md - CORS の標準設定（@elysiajs/cors）
• cron.md - Elysia コンテキストにアクセスできる Cron ジョブを実行（@elysiajs/cron）
• graphql-apollo.md - GraphQL Apollo との統合（@elysiajs/graphql-apollo）
• graphql-yoga.md - GraphQL Yoga との統合（@elysiajs/graphql-yoga）
• html.md - HTML と JSX プラグインのセットアップと使用方法（@elysiajs/html）
• jwt.md - JWT／JWK プラグイン（@elysiajs/jwt）
• openapi.md - OpenAPI ドキュメントと OpenAPI Type Gen／型からの OpenAPI 生成（@elysiajs/openapi）
• opentelemetry.md - OpenTelemetry、計装、スパン記録ユーティリティ（@elysiajs/opentelemetry）
• server-timing.md - デバッグ用の Server Timing メトリクス（@elysiajs/server-timing）
• static.md - Elysia サーバーで静的ファイル／フォルダーを配信（@elysiajs/static）

integrations/

Elysia と外部ライブラリ／ランタイムを統合するためのガイド：

• ai-sdk.md - Elysia で Vercel AI SDK を使用
• astro.md - Astro の API ルートで Elysia を使用
• better-auth.md - Elysia を better-auth と統合
• cloudflare-worker.md - Cloudflare Worker アダプターで Elysia を使用
• deno.md - Deno で Elysia を使用
• drizzle.md - Elysia を Drizzle ORM と統合
• expo.md - Expo の API ルートで Elysia を使用
• nextjs.md - Nextjs の API ルートで Elysia を使用
• nodejs.md - Node.js で Elysia を実行
• nuxt.md - API ルートで Elysia を使用
• prisma.md - Elysia を Prisma と統合
• react-email.d - React と Elysia でメールを作成して送信
• sveltekit.md - Svelte Kit の API ルートで Elysia を実行
• tanstack-start.md - Tanstack Start／React Query で Elysia を実行
• vercel.md - Elysia を Vercel にデプロイ

examples/（任意）

• basic.ts - Elysia の基本的な例
• body-parser.ts - .onParse を使ったカスタムボディパーサーの例
• complex.ts - Elysia サーバーの包括的な使用例
• cookie.ts - Cookie の設定
• error.ts - エラー処理
• file.ts - サーバーからローカルファイルを返す
• guard.ts - 複数のバリデーションスキーマとライフサイクルの設定
• map-response.ts - カスタムレスポンスマッパー
• redirect.ts - リダイレクトレスポンス
• rename.ts - コンテキストのプロパティ名を変更
• schema.ts - バリデーションの設定
• state.ts - グローバル状態の設定
• upload-file.ts - バリデーション付きのファイルアップロード
• websocket.ts - リアルタイム通信用の Web Socket

patterns/（任意）

• patterns/mvc.md - MVC パターンで Elysia を使用するための詳細なガイドライン