NuxtHub v0.10

Full-stack Nuxt framework with database, KV, blob, and cache. Multi-cloud support (Cloudflare, Vercel, Deno, Netlify).

For Nuxt server patterns: use nuxt skill (server.md) For content with database: use nuxt-content skill

Installation

npx nuxi module add @nuxthub/core-nightly

Configuration

// nuxt.config.ts
export default defineNuxtConfig({
  modules: ['@nuxthub/core'],
  hub: {
    db: 'sqlite', // 'sqlite' | 'postgresql' | 'mysql'
    kv: true,
    blob: true,
    cache: true,
    dir: '.data' // local storage directory
  }
})

Advanced Database Config

hub: {
  db: {
    dialect: 'postgresql',
    driver: 'postgres-js', // Optional: auto-detected
    casing: 'snake_case',  // camelCase JS -> snake_case DB
    migrationsDirs: ['server/db/custom-migrations/'],
    applyMigrationsDuringBuild: true // default
  }
}

Database

Type-safe SQL via Drizzle ORM. db and schema are auto-imported on server-side.

Schema Definition

Place in server/db/schema.ts or 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 variant:

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()
})

Database API

// db and schema are auto-imported on server-side
import { db, schema } from 'hub:db'

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

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

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

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

Migrations

npx nuxt db generate              # Generate migrations from schema
npx nuxt db migrate               # Apply pending migrations
npx nuxt db sql "SELECT * FROM users"  # Execute raw SQL
npx nuxt db drop <TABLE>          # Drop a table
npx nuxt db mark-as-migrated [NAME]   # Mark without running

Migrations auto-apply during npx nuxi dev and npx nuxi build. Tracked in _hub_migrations table.

Database Providers

Dialect	Local	Production
sqlite	.data/db/sqlite.db	D1 (Cloudflare), Turso (TURSO_DATABASE_URL, TURSO_AUTH_TOKEN)
postgresql	PGlite	postgres-js (DATABASE_URL), neon-http (DATABASE_URL)
mysql	-	mysql2 (DATABASE_URL, MYSQL_URL)

KV Storage

Key-value storage. kv is auto-imported on server-side.

import { kv } from 'hub:kv'

await kv.set('key', { data: 'value' })
await kv.set('key', value, { ttl: 60 }) // TTL in seconds
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:')

Constraints: max value 25 MiB, max key 512 bytes.

KV Providers

Provider	Package	Env Vars
Upstash	@upstash/redis	UPSTASH_REDIS_REST_URL, UPSTASH_REDIS_REST_TOKEN
Redis	ioredis	REDIS_URL
Cloudflare KV	-	KV binding in wrangler.jsonc
Deno KV	-	Auto on Deno Deploy
Vercel	-	KV_REST_API_URL, KV_REST_API_TOKEN

Blob Storage

File storage. blob is auto-imported on server-side.

Blob API

import { blob } from 'hub:blob'

// Upload
const result = await blob.put('path/file.txt', body, { contentType: 'text/plain', addRandomSuffix: true, prefix: 'uploads' })
// Returns: { pathname, contentType, size, httpEtag, uploadedAt }

// Download
const file = await blob.get('path/file.txt') // Returns Blob or null

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

// Serve (with proper headers)
return blob.serve(event, 'path/file.txt')

// Delete
await blob.del('path/file.txt')
await blob.del(['file1.txt', 'file2.txt']) // Multiple

// Metadata only
const meta = await blob.head('path/file.txt')

Upload Helpers

// Server: Validate + upload handler
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' }
  })
})

// Validate before manual upload
ensureBlob(file, { maxSize: '10MB', types: ['image'] })

// Multipart upload for large files (>10MB)
export default eventHandler(async (event) => {
  return blob.handleMultipartUpload(event) // Route: /api/files/multipart/[action]/[...pathname]
})

Vue Composables

// Simple upload
const upload = useUpload('/api/upload')
const result = await upload(inputElement)

// Multipart with progress
const mpu = useMultipartUpload('/api/files/multipart')
const { completed, progress, abort } = mpu(file)

Blob Providers

Provider	Package	Config
Cloudflare R2	-	BLOB binding in wrangler.jsonc
Vercel Blob	@vercel/blob	BLOB_READ_WRITE_TOKEN
S3	aws4fetch	S3_ACCESS_KEY_ID, S3_SECRET_ACCESS_KEY, S3_BUCKET, S3_REGION

Cache

Response and function caching.

Route Handler Caching

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

Function Caching

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 }
)

Cache Invalidation

// Remove specific
await useStorage('cache').removeItem('nitro:functions:getStars:repo-name.json')

// Clear by prefix
await useStorage('cache').clear('nitro:handlers')

Cache key pattern: ${group}:${name}:${getKey(...args)}.json (defaults: group='nitro', name='handlers'|'functions'|'routes')

Deployment

Cloudflare Workers

Configure bindings in nuxt.config.ts (no wrangler.jsonc needed):

// nuxt.config.ts
export default defineNuxtConfig({
  hub: {
    db: 'sqlite',
    kv: true,
    blob: true,
    cache: true
  },
  nitro: {
    preset: 'cloudflare_module',
    cloudflare: {
      wrangler: {
        compatibility_flags: ['nodejs_compat'],
        d1_databases: [{ binding: 'DB', database_id: '<id>' }],
        kv_namespaces: [
          { binding: 'KV', id: '<kv-id>' },
          { binding: 'CACHE', id: '<cache-id>' }
        ],
        r2_buckets: [{ binding: 'BLOB', bucket_name: '<bucket>' }]
      }
    }
  }
})

Required binding names: DB (D1), KV (KV), CACHE (KV), BLOB (R2).

Create resources via CLI:

npx wrangler d1 create my-app-db          # Get database_id
npx wrangler kv namespace create KV       # Get kv-id
npx wrangler kv namespace create CACHE    # Get cache-id
npx wrangler r2 bucket create my-bucket   # Get bucket name

Deploy via Workers Builds:

1. Workers & Pages > Create > Import from Git
2. Build command: pnpm build
3. Deploy command: npx wrangler deploy

For environments: CLOUDFLARE_ENV=preview nuxt build

See references/wrangler-templates.md for wrangler.jsonc file alternative.

Vercel

Use Vercel Marketplace for compatible storage:

• Database: Vercel Postgres, Turso
• KV: Vercel KV (Upstash)
• Blob: Vercel Blob

D1 over HTTP

Query D1 from non-Cloudflare hosts:

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

Requires: NUXT_HUB_CLOUDFLARE_ACCOUNT_ID, NUXT_HUB_CLOUDFLARE_API_TOKEN, NUXT_HUB_CLOUDFLARE_DATABASE_ID

Build-time Hooks

// Extend schema
nuxt.hook('hub:db:schema:extend', async ({ dialect, paths }) => {
  paths.push(await resolvePath(`./schema/custom.${dialect}`))
})

// Add migration directories
nuxt.hook('hub:db:migrations:dirs', (dirs) => {
  dirs.push(resolve('./db-migrations'))
})

// Post-migration queries (idempotent)
nuxt.hook('hub:db:queries:paths', (paths, dialect) => {
  paths.push(resolve(`./seed.${dialect}.sql`))
})

Type Sharing

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

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

WebSocket / Realtime

Enable experimental 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')
  }
})

Deprecated (v0.10)

Removed Cloudflare-specific features:

• hubAI() -> Use AI SDK with Workers AI Provider
• hubBrowser() -> Puppeteer
• hubVectorize() -> Vectorize
• NuxtHub Admin -> Sunset Dec 31, 2025
• npx nuxthub deploy -> Use wrangler deploy

Quick Reference

Feature	Import	Access
Database	import { db, schema } from 'hub:db'	db.select(), db.insert(), etc.
KV	import { kv } from 'hub:kv'	kv.get(), kv.set(), etc.
Blob	import { blob } from 'hub:blob'	blob.put(), blob.get(), etc.

All are auto-imported on server-side.

Resources

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