nuxthub-wrangler

Nuxt module for Cloudflare Wrangler configuration with NuxtHub integration.

Installation

pnpm add nuxthub-wrangler

Usage

// nuxt.config.ts
export default defineNuxtConfig({
  // IMPORTANT: nuxthub-wrangler MUST come BEFORE @nuxthub/core
  modules: ['nuxthub-wrangler', '@nuxthub/core'],

  hub: {
    db: 'd1:your-database-id',       // sqlite + D1 binding
    blob: 'r2:your-bucket-name',     // blob + R2 binding
    kv: 'kv:your-kv-namespace-id',   // kv + KV binding
    cache: 'kv:your-cache-kv-id'     // cache + KV binding
  },

  wrangler: {
    name: 'my-worker'
  },

  compatibilityDate: '2025-01-01'
})

Shorthand patterns

Pattern	Expands To	Wrangler Binding
hub.db: 'd1:xxx'	hub.db: 'sqlite'	{ binding: 'DB', database_id: 'xxx' }
hub.blob: 'r2:xxx'	hub.blob: true	{ binding: 'BLOB', bucket_name: 'xxx' }
hub.kv: 'kv:xxx'	hub.kv: true	{ binding: 'KV', id: 'xxx' }
hub.cache: 'kv:xxx'	hub.cache: true	{ binding: 'CACHE', id: 'xxx' }

Non-shorthand values

Standard values still work (no binding added):

hub: {
  db: 'sqlite',      // or 'postgresql', 'mysql'
  db: true,
  kv: true,
  blob: true,
  cache: true
}

Full config (power users)

wrangler: {
  d1_databases: [
    { binding: 'DB', database_id: 'xxx' },
    { binding: 'MY_OTHER_DB', database_id: 'yyy' }
  ],
  r2_buckets: [{ binding: 'BLOB', bucket_name: 'xxx' }],
  kv_namespaces: [{ binding: 'KV', id: 'xxx' }, { binding: 'CACHE', id: 'yyy' }],
  vars: { MY_VAR: 'value' },
  observability: { enabled: true }
}

How it works

1. Parses shorthand syntax (d1:, r2:, kv:) from hub config
2. Normalizes hub config for @nuxthub/core (e.g., 'd1:xxx' → 'sqlite')
3. Adds wrangler bindings to Nitro's cloudflare.wrangler option
4. Sets nitro.cloudflare.deployConfig = true
5. Validates binding names match enabled hub features

This module does not override other nitro.cloudflare settings (e.g. nodeCompat) so it composes cleanly with @nuxthub/core.

NuxtHub Binding Names

NuxtHub expects these specific binding names:

Feature	Binding	Type
hub.db	DB	d1_databases
hub.blob	BLOB	r2_buckets
hub.kv	KV	kv_namespaces
hub.cache	CACHE	kv_namespaces

Validation

The module throws an error if you use a NuxtHub binding name without enabling the feature:

• DB binding defined but hub.db not enabled → error
• BLOB binding defined but hub.blob not enabled → error
• KV binding defined but hub.kv not enabled → error
• CACHE binding defined but hub.cache not enabled → error

Custom binding names (e.g., MY_BUCKET) are allowed without enabling hub features.

License

MIT