feat: auto-generate wrangler bindings from hub config (#716)

Co-authored-by: Sébastien Chopin <[email protected]>

Author: onmax

.gitignore

@@ -60,4 +60,5 @@ test/fixtures/basic/.data
 test/fixtures/kv/.data
 test/fixtures/blob/.data
 test/fixtures/openapi/.data
-test/fixtures/cache/.data
+test/fixtures/cache/.data
+test/fixtures/wrangler/.data

src/blob/setup.ts

@@ -3,8 +3,8 @@ import { defu } from 'defu'
 import { addTypeTemplate, addServerImports, addImportsDir, logger, addTemplate } from '@nuxt/kit'
 
 import type { Nuxt } from '@nuxt/schema'
-import type { HubConfig, ResolvedBlobConfig } from '@nuxthub/core'
-import { resolve, logWhenReady } from '../utils'
+import type { HubConfig, ResolvedBlobConfig, CloudflareR2BlobConfig } from '@nuxthub/core'
+import { resolve, logWhenReady, addWranglerBinding } from '../utils'
 
 const log = logger.withTag('nuxt:hub')
 
@@ -70,10 +70,14 @@ export function setupBlob(nuxt: Nuxt, hub: HubConfig, deps: Record<string, strin
 
   const blobConfig = hub.blob as ResolvedBlobConfig
 
+  if (blobConfig.driver === 'cloudflare-r2' && blobConfig.bucketName) {
+    addWranglerBinding(nuxt, 'r2_buckets', { binding: blobConfig.binding || 'BLOB', bucket_name: blobConfig.bucketName })
+  }
+
   // Add Composables
   addImportsDir(resolve('blob/runtime/app/composables'))
 
-  const { driver, ...driverOptions } = blobConfig
+  const { driver, bucketName: _bucketName, ...driverOptions } = blobConfig as CloudflareR2BlobConfig
 
   if (!supportedDrivers.includes(driver as any)) {
     log.error(`Unsupported blob driver: ${driver}. Supported drivers: ${supportedDrivers.join(', ')}`)

src/cache/setup.ts

@@ -1,6 +1,6 @@
 import { join } from 'pathe'
 import { defu } from 'defu'
-import { logWhenReady } from '../utils'
+import { logWhenReady, addWranglerBinding } from '../utils'
 
 import type { Nuxt } from '@nuxt/schema'
 import type { HubConfig, CacheConfig, ResolvedCacheConfig } from '@nuxthub/core'
@@ -47,14 +47,19 @@ export async function setupCache(nuxt: Nuxt, hub: HubConfig, _deps: Record<strin
 
   const cacheConfig = hub.cache as ResolvedCacheConfig
 
+  if (cacheConfig.driver === 'cloudflare-kv-binding' && cacheConfig.namespaceId) {
+    addWranglerBinding(nuxt, 'kv_namespaces', { binding: cacheConfig.binding || 'CACHE', id: cacheConfig.namespaceId })
+  }
+
   // Configure storage
+  const { namespaceId: _namespaceId, ...cacheStorageConfig } = cacheConfig
   nuxt.options.nitro.storage ||= {}
-  nuxt.options.nitro.storage.cache = defu(nuxt.options.nitro.storage.cache, cacheConfig)
+  nuxt.options.nitro.storage.cache = defu(nuxt.options.nitro.storage.cache, cacheStorageConfig)
 
   // Also set devStorage for development mode (fs-lite driver)
   if (nuxt.options.dev) {
     nuxt.options.nitro.devStorage ||= {}
-    nuxt.options.nitro.devStorage.cache = defu(nuxt.options.nitro.devStorage.cache, cacheConfig)
+    nuxt.options.nitro.devStorage.cache = defu(nuxt.options.nitro.devStorage.cache, cacheStorageConfig)
   }
 
   logWhenReady(nuxt, `\`hub:cache\` using \`${cacheConfig.driver.split('/').pop()}\` driver`)

src/db/setup.ts

@@ -4,7 +4,7 @@ import { glob } from 'tinyglobby'
 import { join, resolve as resolveFs, relative } from 'pathe'
 import { defu } from 'defu'
 import { addServerImports, addTemplate, addServerPlugin, addTypeTemplate, getLayerDirectories, updateTemplates, logger, addServerHandler } from '@nuxt/kit'
-import { resolve, resolvePath, logWhenReady } from '../utils'
+import { resolve, resolvePath, logWhenReady, addWranglerBinding } from '../utils'
 import { copyDatabaseMigrationsToHubDir, copyDatabaseQueriesToHubDir, copyDatabaseAssets, applyBuildTimeMigrations, getDatabaseSchemaPathMetadata, buildDatabaseSchema } from './lib'
 import { cloudflareHooks } from '../hosting/cloudflare'
 
@@ -61,6 +61,11 @@ export async function resolveDatabaseConfig(nuxt: Nuxt, hub: HubConfig): Promise
       break
     }
     case 'postgresql': {
+      // Cloudflare Hyperdrive with explicit hyperdriveId
+      if (hub.hosting.includes('cloudflare') && config.connection?.hyperdriveId && !config.driver) {
+        config.driver = 'postgres-js'
+        break
+      }
       config.connection = defu(config.connection, { url: process.env.POSTGRES_URL || process.env.POSTGRESQL_URL || process.env.DATABASE_URL || '' })
       if (config.driver && ['neon-http', 'postgres-js'].includes(config.driver) && !config.connection.url) {
         throw new Error(`\`${config.driver}\` driver requires \`DATABASE_URL\`, \`POSTGRES_URL\`, or \`POSTGRESQL_URL\` environment variable`)
@@ -76,6 +81,11 @@ export async function resolveDatabaseConfig(nuxt: Nuxt, hub: HubConfig): Promise
       break
     }
     case 'mysql': {
+      // Cloudflare Hyperdrive with explicit hyperdriveId
+      if (hub.hosting.includes('cloudflare') && config.connection?.hyperdriveId && !config.driver) {
+        config.driver = 'mysql2'
+        break
+      }
       config.driver ||= 'mysql2'
       config.connection = defu(config.connection, { uri: process.env.MYSQL_URL || process.env.DATABASE_URL || '' })
       if (!config.connection.uri) {
@@ -97,10 +107,18 @@ export async function setupDatabase(nuxt: Nuxt, hub: HubConfig, deps: Record<str
   hub.db = await resolveDatabaseConfig(nuxt, hub)
   if (!hub.db) return
 
-  const { dialect, driver, migrationsDirs, queriesPaths } = hub.db as ResolvedDatabaseConfig
+  const { dialect, driver, connection, migrationsDirs, queriesPaths } = hub.db as ResolvedDatabaseConfig
 
   logWhenReady(nuxt, `\`hub:db\` using \`${dialect}\` database with \`${driver}\` driver`, 'info')
 
+  if (driver === 'd1' && connection?.databaseId) {
+    addWranglerBinding(nuxt, 'd1_databases', { binding: 'DB', database_id: connection.databaseId })
+  }
+  if (['postgres-js', 'mysql2'].includes(driver) && connection?.hyperdriveId) {
+    const binding = driver === 'postgres-js' ? 'POSTGRES' : 'MYSQL'
+    addWranglerBinding(nuxt, 'hyperdrive', { binding, id: connection.hyperdriveId })
+  }
+
   // Verify development database dependencies are installed
   if (!deps['drizzle-orm'] || !deps['drizzle-kit']) {
     logWhenReady(nuxt, 'Please run `npx nypm i drizzle-orm drizzle-kit` to properly setup Drizzle ORM with NuxtHub.', 'error')

src/kv/setup.ts

@@ -1,6 +1,6 @@
 import { defu } from 'defu'
 import { addTypeTemplate, addServerImports, addTemplate } from '@nuxt/kit'
-import { resolve, logWhenReady } from '../utils'
+import { resolve, logWhenReady, addWranglerBinding } from '../utils'
 
 import type { Nuxt } from '@nuxt/schema'
 import type { HubConfig, ResolvedKVConfig } from '@nuxthub/core'
@@ -71,6 +71,10 @@ export function setupKV(nuxt: Nuxt, hub: HubConfig, deps: Record<string, string>
 
   const kvConfig = hub.kv as ResolvedKVConfig
 
+  if (kvConfig.driver === 'cloudflare-kv-binding' && kvConfig.namespaceId) {
+    addWranglerBinding(nuxt, 'kv_namespaces', { binding: kvConfig.binding || 'KV', id: kvConfig.namespaceId })
+  }
+
   // Verify dependencies
   if (kvConfig.driver === 'upstash' && !deps['@upstash/redis']) {
     logWhenReady(nuxt, 'Please run `npx nypm i @upstash/redis` to use Upstash Redis KV storage', 'error')
@@ -83,10 +87,11 @@ export function setupKV(nuxt: Nuxt, hub: HubConfig, deps: Record<string, string>
   }
 
   // Configure production storage
+  const { namespaceId: _namespaceId, ...kvStorageConfig } = kvConfig
   nuxt.options.nitro.storage ||= {}
-  nuxt.options.nitro.storage.kv = defu(nuxt.options.nitro.storage.kv, kvConfig)
+  nuxt.options.nitro.storage.kv = defu(nuxt.options.nitro.storage.kv, kvStorageConfig)
 
-  const { driver, ...driverOptions } = kvConfig
+  const { driver, ...driverOptions } = kvStorageConfig
   const template = addTemplate({
     filename: 'hub/kv.mjs',
     getContents: () => `import { createStorage } from "unstorage"

src/types/config.ts

@@ -74,13 +74,17 @@ export interface ModuleOptions {
 export type FSBlobConfig = { driver: 'fs' } & FSDriverOptions
 export type S3BlobConfig = { driver: 's3' } & S3DriverOptions
 export type VercelBlobConfig = { driver: 'vercel-blob' } & VercelDriverOptions
-export type CloudflareR2BlobConfig = { driver: 'cloudflare-r2' } & CloudflareDriverOptions
+export type CloudflareR2BlobConfig = { driver: 'cloudflare-r2', bucketName?: string } & CloudflareDriverOptions
 
 export type BlobConfig = boolean | FSBlobConfig | S3BlobConfig | VercelBlobConfig | CloudflareR2BlobConfig
 export type ResolvedBlobConfig = FSBlobConfig | S3BlobConfig | VercelBlobConfig | CloudflareR2BlobConfig
 
 export type CacheConfig = {
   driver?: BuiltinDriverName
+  /**
+   * Cloudflare KV namespace ID for auto-generating wrangler bindings
+   */
+  namespaceId?: string
   [key: string]: any
 }
 export type ResolvedCacheConfig = CacheConfig & {
@@ -89,6 +93,10 @@ export type ResolvedCacheConfig = CacheConfig & {
 
 export type KVConfig = {
   driver?: BuiltinDriverName
+  /**
+   * Cloudflare KV namespace ID for auto-generating wrangler bindings
+   */
+  namespaceId?: string
   [key: string]: any
 }
 
@@ -138,9 +146,13 @@ type DatabaseConnection = {
    */
   apiToken?: string
   /**
-   * Cloudflare D1 Database ID (for D1 HTTP driver)
+   * Cloudflare D1 Database ID (for D1 driver and D1 HTTP driver)
    */
   databaseId?: string
+  /**
+   * Cloudflare Hyperdrive ID for auto-generating wrangler bindings (PostgreSQL/MySQL)
+   */
+  hyperdriveId?: string
   /**
    * Additional connection options
    */

src/utils.ts

@@ -17,3 +17,15 @@ export function logWhenReady(nuxt: Nuxt, message: string, type: 'info' | 'warn'
 }
 
 export const { resolve, resolvePath } = createResolver(import.meta.url)
+
+type WranglerBindingType = 'd1_databases' | 'r2_buckets' | 'kv_namespaces' | 'hyperdrive'
+
+export function addWranglerBinding(nuxt: Nuxt, type: WranglerBindingType, binding: { binding: string, [key: string]: any }) {
+  nuxt.options.nitro.cloudflare ||= {}
+  nuxt.options.nitro.cloudflare.wrangler ||= {}
+  nuxt.options.nitro.cloudflare.wrangler[type] ||= []
+  const existing = nuxt.options.nitro.cloudflare.wrangler[type] as Array<{ binding: string }>
+  if (!existing.some(b => b.binding === binding.binding)) {
+    (existing as any[]).push(binding)
+  }
+}

test/fixtures/wrangler/nuxt.config.ts

@@ -0,0 +1,12 @@
+import { defineNuxtConfig } from 'nuxt/config'
+
+export default defineNuxtConfig({
+  extends: ['../basic'],
+  modules: ['../../../src/module'],
+  hub: {
+    blob: { driver: 'cloudflare-r2', bucketName: 'test-bucket', binding: 'BLOB' },
+    kv: { driver: 'cloudflare-kv-binding', namespaceId: 'test-kv-id', binding: 'KV' },
+    cache: { driver: 'cloudflare-kv-binding', namespaceId: 'test-cache-id', binding: 'CACHE' },
+    db: { dialect: 'sqlite', driver: 'd1', connection: { databaseId: 'test-db-id' } }
+  }
+})

test/fixtures/wrangler/package.json

@@ -0,0 +1 @@
+{ "private": true, "name": "hub-wrangler-test", "type": "module" }

test/wrangler.test.ts

@@ -0,0 +1,27 @@
+import { fileURLToPath } from 'node:url'
+import { describe, expect, it } from 'vitest'
+import { setup, useTestContext } from '@nuxt/test-utils'
+import { addWranglerBinding } from '../src/utils'
+
+describe('addWranglerBinding', () => {
+  it('should not add duplicate bindings', () => {
+    const nuxt = { options: { nitro: {} } } as any
+    addWranglerBinding(nuxt, 'kv_namespaces', { binding: 'KV', id: 'first' })
+    addWranglerBinding(nuxt, 'kv_namespaces', { binding: 'KV', id: 'second' })
+    expect(nuxt.options.nitro.cloudflare.wrangler.kv_namespaces).toHaveLength(1)
+  })
+})
+
+describe('wrangler bindings e2e', async () => {
+  await setup({ rootDir: fileURLToPath(new URL('./fixtures/wrangler', import.meta.url)), dev: true })
+
+  it('should auto-generate all wrangler bindings from hub config', () => {
+    const { nuxt } = useTestContext()
+    const wrangler = nuxt?.options.nitro.cloudflare?.wrangler
+
+    expect(wrangler?.r2_buckets).toContainEqual({ binding: 'BLOB', bucket_name: 'test-bucket' })
+    expect(wrangler?.kv_namespaces).toContainEqual({ binding: 'KV', id: 'test-kv-id' })
+    expect(wrangler?.kv_namespaces).toContainEqual({ binding: 'CACHE', id: 'test-cache-id' })
+    expect(wrangler?.d1_databases).toContainEqual({ binding: 'DB', database_id: 'test-db-id' })
+  })
+})