feat: cloudflare hub shorthands

Author: onmax

docs/content/docs/1.getting-started/3.deploy.md

@@ -24,6 +24,34 @@ You can deploy your project on your own Cloudflare account, you need to create t
 You only need to create these resources if you have explicitly enabled them in the `hub` config.
 ::
 
+### Recommended: generate Wrangler bindings from `hub` config
+
+If you deploy using Wrangler (CLI or CI), you can configure Cloudflare resource IDs directly in `nuxt.config.ts` and let Nitro generate the Wrangler config during build:
+
+```ts [nuxt.config.ts]
+export default defineNuxtConfig({
+  modules: ['@nuxthub/core'],
+  hub: {
+    db: 'd1:<database_id>',
+    blob: 'r2:<bucket_name>',
+    kv: 'kv:<namespace_id>',
+    cache: 'kv:<namespace_id>'
+  }
+})
+```
+
+Then deploy the Nuxt output entrypoint (the Wrangler config is generated in `.output/`):
+
+```bash
+npx wrangler deploy .output/server/index.mjs
+```
+
+::note
+If you are using Cloudflare Workers Builds, set your deploy command to use the built output entrypoint (not `npx wrangler deploy` from the repo root).
+::
+
+### Manual (Dashboard bindings / custom Wrangler config)
+
 Then, create a [Cloudflare Workers project](https://dash.cloudflare.com/?to=/:account/workers-and-pages/create) and link your GitHub or GitLab repository.
 
 Once your project is created, open the `Settings` tab and set:

playground/.gitignore

@@ -2,3 +2,5 @@
 
 .wrangler
 .env*.local
+wrangler.toml
+wrangler.json

playground/nuxt.config.ts

@@ -20,17 +20,16 @@ export default defineNuxtConfig({
   compatibilityDate: '2025-12-11',
 
   nitro: {
-    // preset: 'cloudflare-module',
     experimental: {
       websocket: true
     }
   },
 
   hub: {
-    db: 'sqlite',
-    blob: true,
-    kv: true,
-    cache: true
+    db: 'd1:adc66aba-ce5f-40bc-bffc-bc80eb17e0b7',
+    blob: 'r2:playground',
+    kv: 'kv:919a41f11e5649deace923de93d8d9ec',
+    cache: 'kv:c59a5cea9d0f44ad92b92e328c7e8b67'
   },
   hooks: {
     'hub:db:migrations:dirs': (dirs) => {

playground/package.json

@@ -5,7 +5,7 @@
   "scripts": {
     "postinstall": "pnpm -C .. run dev:prepare",
     "dev": "nuxi dev",
-    "build": "nuxi build",
+    "build": "NITRO_PRESET=cloudflare_module nuxi build && node ./scripts/sync-wrangler-config.mjs",
     "preview": "nuxi preview"
   },
   "dependencies": {

playground/scripts/sync-wrangler-config.mjs

@@ -0,0 +1,18 @@
+import fs from 'node:fs'
+
+const inputPath = new URL('../.output/server/wrangler.json', import.meta.url)
+const outputPath = new URL('../wrangler.json', import.meta.url)
+
+if (!fs.existsSync(inputPath)) {
+  process.exit(0)
+}
+
+const config = JSON.parse(fs.readFileSync(inputPath, 'utf8'))
+
+config.main = '.output/server/index.mjs'
+
+if (config.assets && typeof config.assets === 'object') {
+  config.assets.directory = '.output/public'
+}
+
+fs.writeFileSync(outputPath, JSON.stringify(config, null, 2) + '\n', 'utf8')

playground/wrangler.jsonc

@@ -0,0 +1,84 @@
+import type { HubCloudflareConfig, HubConfig } from '../types/config'
+
+type WranglerD1Database = { binding: string, database_id: string }
+type WranglerR2Bucket = { binding: string, bucket_name: string }
+type WranglerKVNamespace = { binding: string, id: string }
+
+export type WranglerConfig = {
+  d1_databases?: WranglerD1Database[]
+  r2_buckets?: WranglerR2Bucket[]
+  kv_namespaces?: WranglerKVNamespace[]
+  [key: string]: unknown
+}
+
+function parsePrefixed(value: unknown, prefix: string): string | undefined {
+  if (typeof value !== 'string') return
+  if (!value.startsWith(prefix)) return
+  const rest = value.slice(prefix.length).trim()
+  if (!rest) return
+  return rest
+}
+
+export function normalizeCloudflareShorthands(hub: HubConfig) {
+  const cloudflare: HubCloudflareConfig = hub.cloudflare || {}
+
+  const d1DatabaseId = parsePrefixed(hub.db, 'd1:')
+  if (d1DatabaseId) {
+    cloudflare.d1DatabaseId = d1DatabaseId
+    hub.db = 'sqlite'
+  }
+
+  const r2BucketName = parsePrefixed(hub.blob, 'r2:')
+  if (r2BucketName) {
+    cloudflare.r2BucketName = r2BucketName
+    hub.blob = true
+  }
+
+  const kvNamespaceId = parsePrefixed(hub.kv, 'kv:')
+  if (kvNamespaceId) {
+    cloudflare.kvNamespaceId = kvNamespaceId
+    hub.kv = true
+  }
+
+  const cacheNamespaceId = parsePrefixed(hub.cache, 'kv:')
+  if (cacheNamespaceId) {
+    cloudflare.cacheNamespaceId = cacheNamespaceId
+    hub.cache = true
+  }
+
+  if (Object.keys(cloudflare).length > 0) {
+    hub.cloudflare = cloudflare
+  }
+}
+
+function upsertByBinding<T extends { binding: string }>(existing: T[] | undefined, additions: T[]): T[] {
+  const next = [...(existing || [])]
+  for (const item of additions) {
+    const index = next.findIndex(existingItem => existingItem.binding === item.binding)
+    if (index === -1) next.push(item)
+    else next[index] = item
+  }
+  return next
+}
+
+export function applyWranglerBindingsFromHubCloudflare(wrangler: WranglerConfig, cloudflare: HubCloudflareConfig | undefined) {
+  if (!cloudflare) return
+
+  if (cloudflare.d1DatabaseId) {
+    wrangler.d1_databases = upsertByBinding(wrangler.d1_databases, [
+      { binding: 'DB', database_id: cloudflare.d1DatabaseId }
+    ])
+  }
+  if (cloudflare.r2BucketName) {
+    wrangler.r2_buckets = upsertByBinding(wrangler.r2_buckets, [
+      { binding: 'BLOB', bucket_name: cloudflare.r2BucketName }
+    ])
+  }
+
+  const kvAdditions: WranglerKVNamespace[] = []
+  if (cloudflare.kvNamespaceId) kvAdditions.push({ binding: 'KV', id: cloudflare.kvNamespaceId })
+  if (cloudflare.cacheNamespaceId) kvAdditions.push({ binding: 'CACHE', id: cloudflare.cacheNamespaceId })
+  if (kvAdditions.length) {
+    wrangler.kv_namespaces = upsertByBinding(wrangler.kv_namespaces, kvAdditions)
+  }
+}

src/cloudflare/wrangler.ts

@@ -12,6 +12,7 @@ import { setupBlob } from './blob/setup'
 import type { ModuleOptions, HubConfig, ResolvedHubConfig } from '@nuxthub/core'
 import { addDevToolsCustomTabs } from './devtools'
 import type { NuxtModule } from '@nuxt/schema'
+import { applyWranglerBindingsFromHubCloudflare, normalizeCloudflareShorthands } from './cloudflare/wrangler'
 
 const log = logger.withTag('nuxt:hub')
 
@@ -45,6 +46,9 @@ export default defineNuxtModule<ModuleOptions>({
       db: false,
       kv: false
     }) as HubConfig
+
+    normalizeCloudflareShorthands(hub)
+
     // resolve the hub directory
     hub.dir = await resolveFs(nuxt.options.rootDir, hub.dir)
 
@@ -100,6 +104,10 @@ export default defineNuxtModule<ModuleOptions>({
           compatibility_flags: ['nodejs_compat']
         })
       }
+
+      // Auto-generate wrangler bindings from hub config (d1:/r2:/kv: shorthands)
+      nuxt.options.nitro.cloudflare.wrangler ||= {}
+      applyWranglerBindingsFromHubCloudflare(nuxt.options.nitro.cloudflare.wrangler, hub.cloudflare)
     }
 
     // Add .data to .gitignore

src/module.ts

@@ -4,13 +4,41 @@ import type { S3DriverOptions } from '@nuxthub/core/blob/drivers/s3'
 import type { VercelDriverOptions } from '@nuxthub/core/blob/drivers/vercel-blob'
 import type { CloudflareDriverOptions } from '@nuxthub/core/blob/drivers/cloudflare-r2'
 
+export type CloudflareD1DatabaseId = `d1:${string}`
+export type CloudflareR2BucketName = `r2:${string}`
+export type CloudflareKVNamespaceId = `kv:${string}`
+
+export interface HubCloudflareConfig {
+  /**
+   * Cloudflare D1 database_id used to generate wrangler bindings.
+   * Filled automatically when using `hub.db: "d1:<database_id>"`.
+   */
+  d1DatabaseId?: string
+  /**
+   * Cloudflare R2 bucket_name used to generate wrangler bindings.
+   * Filled automatically when using `hub.blob: "r2:<bucket_name>"`.
+   */
+  r2BucketName?: string
+  /**
+   * Cloudflare KV namespace id used to generate wrangler bindings for `hub.kv`.
+   * Filled automatically when using `hub.kv: "kv:<namespace_id>"`.
+   */
+  kvNamespaceId?: string
+  /**
+   * Cloudflare KV namespace id used to generate wrangler bindings for `hub.cache`.
+   * Filled automatically when using `hub.cache: "kv:<namespace_id>"`.
+   */
+  cacheNamespaceId?: string
+}
+
 export interface HubConfig {
-  blob: boolean | BlobConfig
-  cache: boolean | CacheConfig
-  db: false | 'postgresql' | 'sqlite' | 'mysql' | DatabaseConfig
-  kv: boolean | KVConfig
+  blob: boolean | BlobConfig | CloudflareR2BucketName
+  cache: boolean | CacheConfig | CloudflareKVNamespaceId
+  db: false | 'postgresql' | 'sqlite' | 'mysql' | DatabaseConfig | CloudflareD1DatabaseId
+  kv: boolean | KVConfig | CloudflareKVNamespaceId
   dir: string
   hosting: string
+  cloudflare?: HubCloudflareConfig
 }
 
 export interface ResolvedHubConfig extends HubConfig {
@@ -29,35 +57,39 @@ export interface ModuleOptions {
   /**
    * Set `true` to enable blob storage with auto-configuration.
    * Or provide a BlobConfig object with driver and connection details.
+   * Or provide a Cloudflare shorthand string like `"r2:<bucket_name>"` to auto-generate wrangler bindings.
    *
    * @default false
    * @see https://hub.nuxt.com/docs/features/blob
    */
-  blob?: boolean | BlobConfig
+  blob?: boolean | BlobConfig | CloudflareR2BucketName
   /**
    * Set `true` to enable caching for the project with auto-configuration.
    * Or provide a CacheConfig object with driver and connection details.
+   * Or provide a Cloudflare shorthand string like `"kv:<namespace_id>"` to auto-generate wrangler bindings.
    *
    * @default false
    * @see https://hub.nuxt.com/docs/features/cache
    */
-  cache?: boolean | CacheConfig
+  cache?: boolean | CacheConfig | CloudflareKVNamespaceId
   /**
    * Set to `'postgresql'`, `'sqlite'`, or `'mysql'` to use a specific database dialect with a zero-config development database.
    * Or provide a DatabaseConfig object with dialect and connection details.
+   * Or provide a Cloudflare shorthand string like `"d1:<database_id>"` to use SQLite locally and auto-generate wrangler bindings.
    *
    * @default false
    * @see https://hub.nuxt.com/docs/features/database
    */
-  db?: 'postgresql' | 'sqlite' | 'mysql' | DatabaseConfig | false
+  db?: 'postgresql' | 'sqlite' | 'mysql' | DatabaseConfig | CloudflareD1DatabaseId | false
   /**
    * Set `true` to enable the key-value storage with auto-configuration.
    * Or provide a KVConfig object with driver and connection details.
+   * Or provide a Cloudflare shorthand string like `"kv:<namespace_id>"` to auto-generate wrangler bindings.
    *
    * @default false
    * @see https://hub.nuxt.com/docs/features/kv
    */
-  kv?: boolean | KVConfig
+  kv?: boolean | KVConfig | CloudflareKVNamespaceId
   /**
    * The directory used for storage (database, kv, etc.) during local development.
    * @default '.data'

src/types/config.ts

@@ -0,0 +1,51 @@
+import { describe, it, expect } from 'vitest'
+import type { HubConfig } from '../src/types'
+import { applyWranglerBindingsFromHubCloudflare, normalizeCloudflareShorthands } from '../src/cloudflare/wrangler'
+
+describe('cloudflare wrangler bindings', () => {
+  it('normalizes hub shorthands into hub.cloudflare + updates hub flags', () => {
+    const hub: HubConfig = {
+      hosting: 'cloudflare_module',
+      dir: '.data',
+      db: 'd1:db-id',
+      blob: 'r2:bucket-name',
+      kv: 'kv:kv-id',
+      cache: 'kv:cache-id'
+      // ignored by this test
+    } as any
+
+    normalizeCloudflareShorthands(hub)
+
+    expect(hub.db).toBe('sqlite')
+    expect(hub.blob).toBe(true)
+    expect(hub.kv).toBe(true)
+    expect(hub.cache).toBe(true)
+    expect(hub.cloudflare).toEqual({
+      d1DatabaseId: 'db-id',
+      r2BucketName: 'bucket-name',
+      kvNamespaceId: 'kv-id',
+      cacheNamespaceId: 'cache-id'
+    })
+  })
+
+  it('applies wrangler bindings without clobbering other bindings', () => {
+    const wrangler = {
+      kv_namespaces: [{ binding: 'OTHER', id: 'x' }]
+    } as any
+
+    applyWranglerBindingsFromHubCloudflare(wrangler, {
+      d1DatabaseId: 'db-id',
+      r2BucketName: 'bucket-name',
+      kvNamespaceId: 'kv-id',
+      cacheNamespaceId: 'cache-id'
+    })
+
+    expect(wrangler.d1_databases).toEqual([{ binding: 'DB', database_id: 'db-id' }])
+    expect(wrangler.r2_buckets).toEqual([{ binding: 'BLOB', bucket_name: 'bucket-name' }])
+    expect(wrangler.kv_namespaces).toEqual([
+      { binding: 'OTHER', id: 'x' },
+      { binding: 'KV', id: 'kv-id' },
+      { binding: 'CACHE', id: 'cache-id' }
+    ])
+  })
+})