NuxtHub v0.10.6

データベース、KV、blob、キャッシュを備えたフルスタック Nuxt フレームワーク。マルチクラウド対応 (Cloudflare、Vercel、Deno、Netlify)。

Nuxt サーバーパターンの場合: nuxt skill (server.md) を使用してください データベース付きコンテンツの場合: nuxt-content skill を使用してください

ファイルの読み込み

タスクに応じてこれらのリファレンスファイルの読み込みを検討してください:

• references/wrangler-templates.md - Cloudflare デプロイメント用に wrangler.jsonc を手動で設定する場合
• references/providers.md - Vercel、Netlify、Deno、AWS にデプロイする場合、または外部データベース/ストレージプロバイダーを設定する場合

すべてのファイルを一度に読み込まないでください。 現在のタスクに関連するもののみを読み込んでください。

インストール

npx nuxi module add hub

設定

// nuxt.config.ts
export default defineNuxtConfig({
  modules: ['@nuxthub/core'],
  hub: {
    db: 'sqlite', // 'sqlite' | 'postgresql' | 'mysql'
    kv: true,
    blob: true,
    cache: true,
    dir: '.data', // ローカルストレージディレクトリ
    remote: false // 開発環境で本番バインディングを使用 (v0.10+)
  }
})

高度な設定

hub: {
  db: {
    dialect: 'postgresql',
    driver: 'postgres-js', // オプション: 自動検出
    casing: 'snake_case',  // camelCase JS -> snake_case DB (v0.10.3+)
    migrationsDirs: ['server/db/custom-migrations/'],
    applyMigrationsDuringBuild: true, // デフォルト
    replica: { // 読み取りレプリカサポート (v0.10.6+)
      connection: { connectionString: process.env.DATABASE_REPLICA_URL }
    }
  },
  remote: true // 開発環境で本番 Cloudflare バインディングを使用 (v0.10+)
}

リモートモード: 有効にすると、ローカルエミュレーションの代わりにローカル開発時に本番 D1/KV/R2 に接続します。本番データでのテストに便利です。

データベースレプリカ (v0.10.6+): 読み取りレプリカを設定してデータベース負荷を分散させます。クエリは自動的にレプリカを使用し、書き込みはプライマリに送られます。

データベース

Drizzle ORM を使用した型安全な SQL。db と schema はサーバー側で自動インポートされます。

スキーマ定義

server/db/schema.ts または server/db/schema/*.ts に配置します:

// server/db/schema.ts (SQLite)
import { integer, sqliteTable, text } from 'drizzle-orm/sqlite-core'

export const users = sqliteTable('users', {
  id: integer().primaryKey({ autoIncrement: true }),
  name: text().notNull(),
  email: text().notNull().unique(),
  createdAt: integer({ mode: 'timestamp' }).notNull()
})

PostgreSQL バージョン:

import { pgTable, serial, text, timestamp } from 'drizzle-orm/pg-core'

export const users = pgTable('users', {
  id: serial().primaryKey(),
  name: text().notNull(),
  email: text().notNull().unique(),
  createdAt: timestamp().notNull().defaultNow()
})

データベース API

// db と schema はサーバー側で自動インポートされます
import { db, schema } from 'hub:db'

// 選択
const users = await db.select().from(schema.users)
const user = await db.query.users.findFirst({ where: eq(schema.users.id, 1) })

// 挿入
const [newUser] = await db.insert(schema.users).values({ name: 'John', email: 'john@example.com' }).returning()

// 更新
await db.update(schema.users).set({ name: 'Jane' }).where(eq(schema.users.id, 1))

// 削除
await db.delete(schema.users).where(eq(schema.users.id, 1))

マイグレーション

npx nuxt db generate                  # スキーマからマイグレーションを生成
npx nuxt db migrate                   # 保留中のマイグレーションを適用
npx nuxt db sql "SELECT * FROM users" # 生 SQL を実行
npx nuxt db drop <TABLE>              # 特定のテーブルを削除
npx nuxt db drop-all                  # すべてのテーブルを削除 (v0.10+)
npx nuxt db squash                    # マイグレーションを 1 つに圧縮 (v0.10+)
npx nuxt db mark-as-migrated [NAME]   # 実行せずにマイグレーション済みとしてマーク

マイグレーションは npx nuxi dev と npx nuxi build 中に自動的に適用されます。_hub_migrations テーブルで追跡されます。

データベースプロバイダー

Dialect	ローカル	本番環境
sqlite	.data/db/sqlite.db	D1 (Cloudflare)、Turso (TURSO_DATABASE_URL、TURSO_AUTH_TOKEN)
postgresql	PGlite	postgres-js (DATABASE_URL)、neon-http (v0.10.2+、DATABASE_URL)
mysql	-	mysql2 (DATABASE_URL、MYSQL_URL)

KV ストレージ

キーバリューストレージ。kv はサーバー側で自動インポートされます。

import { kv } from 'hub:kv'

await kv.set('key', { data: 'value' })
await kv.set('key', value, { ttl: 60 }) // TTL（秒単位）
const value = await kv.get('key')
const exists = await kv.has('key')
await kv.del('key')
const keys = await kv.keys('prefix:')
await kv.clear('prefix:')

制限: 最大値 25 MiB、最大キー 512 バイト。

KV プロバイダー

プロバイダー	パッケージ	環境変数
Upstash	@upstash/redis	UPSTASH_REDIS_REST_URL、UPSTASH_REDIS_REST_TOKEN
Redis	ioredis	REDIS_URL
Cloudflare KV	-	wrangler.jsonc の KV バインディング
Deno KV	-	Deno Deploy で自動
Vercel	-	KV_REST_API_URL、KV_REST_API_TOKEN

Blob ストレージ

ファイルストレージ。blob はサーバー側で自動インポートされます。

Blob API

import { blob } from 'hub:blob'

// アップロード
const result = await blob.put('path/file.txt', body, {
  contentType: 'text/plain',
  access: 'public', // 'public' | 'private' (v0.10.2+)
  addRandomSuffix: true,
  prefix: 'uploads'
})
// 戻り値: { pathname, contentType, size, httpEtag, uploadedAt }

// ダウンロード
const file = await blob.get('path/file.txt') // Blob または null を戻す

// リスト
const { blobs, cursor, hasMore, folders } = await blob.list({ prefix: 'uploads/', limit: 10, folded: true })

// サーブ (適切なヘッダー付き)
return blob.serve(event, 'path/file.txt')

// 削除
await blob.del('path/file.txt')
await blob.del(['file1.txt', 'file2.txt']) // 複数

// メタデータのみ
const meta = await blob.head('path/file.txt')

アップロードヘルパー

// サーバー: 検証 + アップロードハンドラー
export default eventHandler(async (event) => {
  return blob.handleUpload(event, {
    formKey: 'files',
    multiple: true,
    ensure: { maxSize: '10MB', types: ['image/png', 'image/jpeg'] },
    put: { addRandomSuffix: true, prefix: 'images' }
  })
})

// 手動アップロード前に検証
ensureBlob(file, { maxSize: '10MB', types: ['image'] })

// 大きなファイル用マルチパートアップロード (>10MB)
export default eventHandler(async (event) => {
  return blob.handleMultipartUpload(event) // ルート: /api/files/multipart/[action]/[...pathname]
})

Vue コンポーザブル

// シンプルアップロード
const upload = useUpload('/api/upload')
const result = await upload(inputElement)

// 進行状況付きマルチパート
const mpu = useMultipartUpload('/api/files/multipart')
const { completed, progress, abort } = mpu(file)

Blob プロバイダー

プロバイダー	パッケージ	設定
Cloudflare R2	-	wrangler.jsonc の BLOB バインディング
Vercel Blob	@vercel/blob	BLOB_READ_WRITE_TOKEN
S3	aws4fetch	S3_ACCESS_KEY_ID、S3_SECRET_ACCESS_KEY、S3_BUCKET、S3_REGION

キャッシュ

レスポンスと関数のキャッシング。

ルートハンドラーキャッシング

export default cachedEventHandler((event) => {
  return { data: 'cached', date: new Date().toISOString() }
}, {
  maxAge: 60 * 60, // 1 時間
  getKey: event => event.path
})

関数キャッシング

export const getStars = defineCachedFunction(
  async (event: H3Event, repo: string) => {
    const data = await $fetch(`https://api.github.com/repos/${repo}`)
    return data.stargazers_count
  },
  { maxAge: 3600, name: 'ghStars', getKey: (event, repo) => repo }
)

キャッシュ無効化

// 特定のものを削除
await useStorage('cache').removeItem('nitro:functions:getStars:repo-name.json')

// プレフィックスで クリア
await useStorage('cache').clear('nitro:handlers')

キャッシュキーパターン: ${group}:${name}:${getKey(...args)}.json (デフォルト: group='nitro'、name='handlers'|'functions'|'routes')

デプロイメント

Cloudflare

NuxtHub は hub 設定から wrangler.json を自動生成します - 手動で wrangler.jsonc は必要ありません:

// nuxt.config.ts
export default defineNuxtConfig({
  hub: {
    db: {
      dialect: 'sqlite',
      driver: 'd1',
      connection: { databaseId: '<database-id>' }
    },
    kv: {
      driver: 'cloudflare-kv-binding',
      namespaceId: '<kv-namespace-id>'
    },
    cache: {
      driver: 'cloudflare-kv-binding',
      namespaceId: '<cache-namespace-id>'
    },
    blob: {
      driver: 'cloudflare-r2',
      bucketName: '<bucket-name>'
    }
  }
})

可観測性 (推奨): 本番デプロイメント用にロギングを有効にします:

// wrangler.jsonc (オプション)
{
  "observability": {
    "logs": {
      "enabled": true,
      "head_sampling_rate": 1,
      "invocation_logs": true,
      "persist": true
    }
  }
}

Cloudflare ダッシュボードまたは CLI でリソースを作成します:

npx wrangler d1 create my-db              # database-id を取得
npx wrangler kv namespace create KV       # kv-namespace-id を取得
npx wrangler kv namespace create CACHE    # cache-namespace-id を取得
npx wrangler r2 bucket create my-bucket   # bucket-name を取得

デプロイ: Cloudflare Workers プロジェクトを作成し、Git リポジトリをリンクします。バインディングはビルド時に自動設定されます。

環境: プレビューデプロイメント用に CLOUDFLARE_ENV=preview を使用します。

手動 wrangler.jsonc パターンについては references/wrangler-templates.md を、すべてのプロバイダー設定については references/providers.md を参照してください。

その他のプロバイダー

次のデプロイメントパターンの詳細については references/providers.md を参照してください:

• Vercel: Postgres、Turso、Vercel Blob、Vercel KV
• Netlify: 外部データベース、S3、Upstash Redis
• Deno Deploy: Deno KV
• AWS/Self-hosted: S3、RDS、カスタム設定

D1 over HTTP

Cloudflare 以外のホストから D1 をクエリします:

hub: {
  db: { dialect: 'sqlite', driver: 'd1-http' }
}

必須: NUXT_HUB_CLOUDFLARE_ACCOUNT_ID、NUXT_HUB_CLOUDFLARE_API_TOKEN、NUXT_HUB_CLOUDFLARE_DATABASE_ID

ビルド時フック

// スキーマを拡張
nuxt.hook('hub:db:schema:extend', async ({ dialect, paths }) => {
  paths.push(await resolvePath(`./schema/custom.${dialect}`))
})

// マイグレーションディレクトリを追加
nuxt.hook('hub:db:migrations:dirs', (dirs) => {
  dirs.push(resolve('./db-migrations'))
})

// マイグレーション後のクエリ (べき等)
nuxt.hook('hub:db:queries:paths', (paths, dialect) => {
  paths.push(resolve(`./seed.${dialect}.sql`))
})

型の共有

// shared/types/db.ts
import type { users } from '~/server/db/schema'

export type User = typeof users.$inferSelect
export type NewUser = typeof users.$inferInsert

WebSocket / リアルタイム

実験的 WebSocket を有効にします:

// nuxt.config.ts
nitro: { experimental: { websocket: true } }

// server/routes/ws/chat.ts
export default defineWebSocketHandler({
  open(peer) {
    peer.subscribe('chat')
    peer.publish('chat', 'User joined')
  },
  message(peer, message) {
    peer.publish('chat', message.text())
  },
  close(peer) {
    peer.unsubscribe('chat')
  }
})

非推奨 (v0.10)

削除された Cloudflare 固有の機能:

• hubAI() -> AI SDK with Workers AI Provider を使用
• hubBrowser() -> Puppeteer
• hubVectorize() -> Vectorize
• NuxtHub Admin -> 2025 年 12 月 31 日にサンセット
• npx nuxthub deploy -> wrangler deploy を使用

クイックリファレンス

機能	インポート	アクセス
Database	import { db, schema } from 'hub:db'	db.select()、db.insert() など
KV	import { kv } from 'hub:kv'	kv.get()、kv.set() など
Blob	import { blob } from 'hub:blob'	blob.put()、blob.get() など

すべてはサーバー側で自動インポートされます。

リソース

• Installation
• Migration from v0.9
• Database
• Blob
• KV
• Cache
• Deploy