Environments · NuxtHub

NuxtHub supports multiple deployment environments, each with isolated resources such as databases, KV stores, and buckets. This guide explains how to configure environments across different hosting providers.

Environment Types

Environment	Purpose	Trigger
Production	Live application serving end users	Push to main branch
Preview	Testing pull requests and feature branches	Push to non-main branches
Staging	Pre-production testing environment	Named environment in configuration
Local	Development on your machine	Running `nuxt dev`

Local Development

During local development, NuxtHub stores data in the .data/ directory:

Resource	Local Path
SQLite/D1	`.data/db/sqlite.db`
PostgreSQL	`.data/db/`
KV	`.data/kv/`
Blob	`.data/blob/`
Cache	`.data/cache/`

The .data/ directory is included in .gitignore by default in Nuxt projects.

Connecting to Remote Resources

To develop against production or preview data, set environment variables that point to your remote resources:

.env.local

# Connect to a remote Turso database
TURSO_DATABASE_URL=libsql://<your-db>.turso.io
TURSO_AUTH_TOKEN=<your-token>

# Or connect to a remote PostgreSQL database
POSTGRES_URL=postgresql://<user>:<password>@<host>/<database>

Connecting to production databases during development risks accidental data modifications. Use a preview or staging environment instead.

Cloudflare Dev Emulation

Nitro runs Cloudflare's local dev emulation when you use the cloudflare_module preset. This replaces NuxtHub's default local storage and requires a wrangler.jsonc with bindings:

wrangler.jsonc

{
  "$schema": "node_modules/wrangler/config-schema.json",
  "d1_databases": [{ "binding": "DB" }],
  "kv_namespaces": [{ "binding": "KV" }, { "binding": "CACHE" }],
  "r2_buckets": [{ "binding": "BLOB" }]
}

Without this file, Nitro throws binding errors such as R2 binding "BLOB" not found or D1 binding "DB" not found.

Cloudflare dev emulation is only used when you explicitly set nitro.preset: 'cloudflare_module' in your nuxt.config.ts.

Production Environments

Cloudflare Workers supports named environments for managing staging, preview, and other deployment targets.

Configuration

Define environment-specific bindings in your wrangler.jsonc file:

wrangler.jsonc

{
  "$schema": "node_modules/wrangler/config-schema.json",
  // Production configuration (default)
  "d1_databases": [
    { "binding": "DB", "database_id": "<production-db-id>" }
  ],
  "kv_namespaces": [
    { "binding": "KV", "id": "<production-kv-id>" }
  ],
  "r2_buckets": [
    { "binding": "BLOB", "bucket_name": "<production-bucket>" }
  ],
  // Named environments
  "env": {
    "preview": {
      "d1_databases": [
        { "binding": "DB", "database_id": "<preview-db-id>" }
      ],
      "kv_namespaces": [
        { "binding": "KV", "id": "<preview-kv-id>" }
      ],
      "r2_buckets": [
        { "binding": "BLOB", "bucket_name": "<preview-bucket>" }
      ]
    },
    "staging": {
      "d1_databases": [
        { "binding": "DB", "database_id": "<staging-db-id>" }
      ],
      "kv_namespaces": [
        { "binding": "KV", "id": "<staging-kv-id>" }
      ],
      "r2_buckets": [
        { "binding": "BLOB", "bucket_name": "<staging-bucket>" }
      ]
    }
  }
}

The d1_databases, kv_namespaces, r2_buckets, vars, durable_objects, and services properties are non-inheritable. You must specify them explicitly in each environment configuration.

Deploying to an Environment

Set the CLOUDFLARE_ENV environment variable during the build process:

Terminal

# Deploy to the preview environment
CLOUDFLARE_ENV=preview nuxt build

# Deploy to the staging environment
CLOUDFLARE_ENV=staging nuxt build

When CLOUDFLARE_ENV is empty or unset, the default production environment is used.

See the CI/CD guide for complete GitHub Actions workflows with environment handling.

Creating Resources

Create separate resources for each environment using the Wrangler CLI:

D1 Databases:

Terminal

wrangler d1 create my-app-production
wrangler d1 create my-app-preview
wrangler d1 create my-app-staging

KV Namespaces:

Terminal

wrangler kv namespace create KV
wrangler kv namespace create KV --env preview
wrangler kv namespace create KV --env staging

R2 Buckets:

Terminal

wrangler r2 bucket create my-app-production
wrangler r2 bucket create my-app-preview
wrangler r2 bucket create my-app-staging

Learn more about Wrangler environments in the Cloudflare documentation.

Vercel automatically manages environments based on branch and deployment type.

Configuration

Configure environment variables in the Vercel dashboard under Project Settings → Environment Variables:

Variable	Production	Preview	Development
`DATABASE_URL`	Production connection	Preview connection	Local connection
`BLOB_READ_WRITE_TOKEN`	Production token	Preview token	Development token

Add storage through the Vercel Marketplace. By default, marketplace integrations connect to all environments—create separate storage instances per environment for isolation.

Branch-Specific Variables

For preview deployments, you can configure variables that apply only to specific branches:

Navigate to Project Settings → Environment Variables
Add a variable and select Preview
Click Add Branch to target specific branches

CI/CD

Vercel handles CI/CD automatically when you connect your repository. Every push triggers a deployment:

Pushes to the production branch deploy to production
Pushes to other branches create preview deployments

Learn more about Vercel environments in the Vercel documentation.