Migrating from v0.9 to v0.10

NuxtHub v0.10 introduces a significant shift toward multi-cloud support and self-hosting, moving away from the Cloudflare-exclusive approach of older versions. This guide will help you migrate your existing v0.9 project to v0.10.

Overview of Changes

Philosophy Shift

• Multi-cloud first: NuxtHub now supports Cloudflare, Vercel, AWS, and other providers
• Self-hosting recommended: Direct integration with your cloud provider instead of NuxtHub Admin (sunset Dec 31, 2025)
• Drizzle ORM integration: Type-safe database access with PostgreSQL, MySQL, and SQLite support
• Cloud-agnostic storage: Blob, KV, and Cache work across multiple providers

Breaking Changes Summary

Configuration Migration

Database

The database option has been renamed to db and now requires specifying the SQL dialect:

export default defineNuxtConfig({
  hub: {
-   database: true
+   db: 'sqlite' // or 'postgresql', 'mysql'
  }
})

For advanced configuration with explicit driver and connection details:

export default defineNuxtConfig({
  hub: {
    db: {
      dialect: 'postgresql',
      driver: 'postgres-js', // Optional: auto-detected from env vars
      connection: {
        connectionString: process.env.DATABASE_URL
      }
    }
  }
})

Directory Structure

Move your database files from server/database/ to server/db/:

# Move schema files
mv server/database/schema.ts server/db/schema.ts

# Move migrations
mv server/database/migrations/ server/db/migrations/

Blob, KV & Cache

These features remain largely the same but now support multiple providers:

export default defineNuxtConfig({
  hub: {
    blob: true,  // Auto-configures based on provider
    kv: true,    // Auto-configures based on provider
    cache: true  // Auto-configures based on provider
  }
})

Code Migration

Database Access

Replace hubDatabase() with Drizzle ORM:

Before (v0.x):

export default eventHandler(async () => {
  const db = hubDatabase()
  const users = await db.prepare('SELECT * FROM users').all()
  return users.results
})

After (v0.10):

import { db, schema } from 'hub:db'

export default eventHandler(async () => {
  return await db.select().from(schema.users)
})

Schema Definition

Create your schema using Drizzle ORM syntax:

import { sqliteTable, text, integer } 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()
})

import { pgTable, text, serial, 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()
})

import { mysqlTable, text, serial, timestamp } from 'drizzle-orm/mysql-core'

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

Then generate migrations:

npx nuxt db generate

Blob Access

Replace hubBlob() with the new blob import:

Before (v0.x):

export default eventHandler(async (event) => {
  const { pathname } = getRouterParams(event)
  return hubBlob().serve(event, pathname)
})

After (v0.10):

import { blob } from 'hub:blob'

export default eventHandler(async (event) => {
  const { pathname } = getRouterParams(event)
  return blob.serve(event, pathname)
})

KV Access

Replace hubKV() with the new kv import:

Before (v0.x):

export default eventHandler(async () => {
  const kv = hubKV()
  return await kv.get('my-key')
})

After (v0.10):

import { kv } from 'hub:kv'

export default eventHandler(async () => {
  return await kv.get('my-key')
})

Self-Hosting Setup

With NuxtHub v0.10, you deploy your project directly to your cloud provider using their tooling.

Cloudflare

NuxtHub supports two approaches for Cloudflare deployment. Choose based on your preference.

Option A: Auto-Configuration (Recommended)

NuxtHub auto-generates the wrangler.json file at build time when you provide resource IDs in your config. No manual wrangler.jsonc is required.

1. Create the necessary resources in your Cloudflare dashboard:
   • D1 Database (if using hub.db)
   • KV Namespace (if using hub.kv or hub.cache)
   • R2 Bucket (if using hub.blob)
2. Configure bindings in nuxt.config.ts:

export default defineNuxtConfig({
  hub: {
    // D1 database
    db: {
      dialect: 'sqlite',
      driver: 'd1',
      connection: { databaseId: '<database-id>' }
    },
    // KV namespace (binding defaults to 'KV')
    kv: {
      driver: 'cloudflare-kv-binding',
      namespaceId: '<kv-namespace-id>'
    },
    // Cache KV namespace (binding defaults to 'CACHE')
    cache: {
      driver: 'cloudflare-kv-binding',
      namespaceId: '<cache-namespace-id>'
    },
    // R2 bucket (binding defaults to 'BLOB')
    blob: {
      driver: 'cloudflare-r2',
      bucketName: '<bucket-name>'
    }
  }
})

3. Deploy using Workers Builds or Pages CI

Option B: Manual wrangler.jsonc

Alternatively, you can create a wrangler.jsonc file manually in your project root:

{
  "$schema": "node_modules/wrangler/config-schema.json",
  "d1_databases": [
    {
      "binding": "DB",
      "database_name": "<database-name>",
      "database_id": "<database-id>"
    }
  ],
  "r2_buckets": [
    {
      "binding": "BLOB",
      "bucket_name": "<bucket-name>"
    }
  ],
  "kv_namespaces": [
    {
      "binding": "KV",
      "id": "<kv-namespace-id>"
    },
    {
      "binding": "CACHE",
      "id": "<cache-namespace-id>"
    }
  ]
}

Vercel

1. Install required packages based on features used:

# For blob storage
npm install @vercel/blob

# For KV/Cache (Upstash Redis)
npm install @upstash/redis

# For PostgreSQL database
npm install drizzle-orm drizzle-kit postgres @electric-sql/pglite

2. Add storage from the Vercel dashboard → Project → Storage
3. Deploy as usual - NuxtHub auto-detects Vercel environment variables

Deprecated Features

The following features have been removed in v0.10 as part of the multi-cloud strategy:

AI & AutoRAG

Use the AI SDK with the Workers AI Provider instead:

// Before (v0.x)
const ai = hubAI()
const result = await ai.run('@cf/meta/llama-2-7b-chat-int8', { prompt: 'Hello' })

// After (v0.10) - use AI SDK
import { generateText } from 'ai'
import { workersai } from 'workers-ai-provider'

const result = await generateText({
  model: workersai('@cf/meta/llama-2-7b-chat-int8'),
  prompt: 'Hello'
})

Browser (Puppeteer)

Access Cloudflare's Browser Rendering directly via process.env.BROWSER binding.

Vectorize

Use Cloudflare's Vectorize binding directly or consider alternatives like Pinecone or Weaviate.

NuxtHub CLI

Replace npx nuxthub deploy with your provider's deployment method:

• Cloudflare: Use wrangler deploy or Workers/Pages CI
• Vercel: Use vercel deploy or Git integration
• Other: Use your provider's CLI or CI/CD

Migration Checklist

• Update nuxt.config.ts: Change database: true to db: '<dialect>'
• Move files from server/database/ to server/db/
• Install Drizzle ORM and appropriate database driver
• Update schema files to use Drizzle ORM syntax
• Generate migrations with npx nuxt db generate
• Replace hubDatabase() calls with db from hub:db
• Replace hubBlob() calls with blob from hub:blob
• Replace hubKV() calls with kv from hub:kv
• Remove AI/AutoRAG usage or migrate to AI SDK
• For Cloudflare: Configure resource IDs in nuxt.config.ts (v0.10.3+) OR create manual wrangler.jsonc
• For Vercel: Add storage from dashboard and install required packages
• Update CI/CD from NuxtHub GitHub Action to provider's deployment (Workers/Pages CI, Vercel Git integration, etc.)

Getting Help

If you encounter issues during migration:

• Use the Claude Code migration skill for AI-assisted migration
• Check the NuxtHub documentation
• Join the Nuxt Discord for community support
• Open an issue on GitHub