Cloudflare

#Cloudflare Workers

Preset: cloudflare_module

The following shows an example nitro.config.ts file for deploying a Nitro app to Cloudflare Workers.

export default defineNitroConfig({
    compatibilityDate: "2024-09-19",
    preset: "cloudflare_module",
    cloudflare: {
      deployConfig: true,
      nodeCompat: true
    }
})

By setting deployConfig: true, Nitro will automatically generate a wrangler.json for you with the correct configuration. If you need to add Cloudflare Workers configuration, such as bindings, you can either:

• Set these in your Nitro config under the cloudflare: { wrangler : {} }. This has the same type as wrangler.json.
• Provide your own wrangler.json. Nitro will merge your config with the appropriate settings, including pointing to the build output.

#Local Preview

You can use Wrangler to preview your app locally:

npm run build

npx wrangler dev

#Manual Deploy

After having built your application you can manually deploy it with Wrangler.

First make sure to be logged into your Cloudflare account:

npx wrangler login

Then you can deploy the application with:

npx wrangler deploy

#Runtime Hooks

You can use runtime hooks below in order to extend Worker handlers.

• cloudflare:scheduled
• cloudflare:email
• cloudflare:queue
• cloudflare:tail
• cloudflare:trace

#Cloudflare Pages

Preset: cloudflare_pages

The following shows an example nitro.config.ts file for deploying a Nitro app to Cloudflare Pages.

export default defineNitroConfig({
    preset: "cloudflare_pages",
    cloudflare: {
      deployConfig: true,
      nodeCompat:true
    }
})

Nitro automatically generates a _routes.json file that controls which routes get served from files and which are served from the Worker script. The auto-generated routes file can be overridden with the config option cloudflare.pages.routes (read more).

#Local Preview

You can use Wrangler to preview your app locally:

npm run build

npx wrangler pages dev

#Manual Deploy

After having built your application you can manually deploy it with Wrangler, in order to do so first make sure to be logged into your Cloudflare account:

npx wrangler login

Then you can deploy the application with:

npx wrangler pages deploy

#Cloudflare Service Workers

Preset: cloudflare

The way this preset works is identical to that of the cloudflare_module one presented above, with the only difference being that such preset inherits all the disadvantages that such syntax brings.

#Deploy within CI/CD using GitHub Actions

Regardless on whether you're using Cloudflare Pages or Cloudflare Workers, you can use the Wrangler GitHub actions to deploy your application.

#Environment Variables

Nitro allows you to universally access environment variables using process.env or import.meta.env or the runtime config.

Example: If you have set the SECRET and NITRO_HELLO_THERE environment variables set you can access them in the following way:

console.log(process.env.SECRET) // note that this is in the global scope! so it doesn't actually work and the variable is undefined!

export default defineEventHandler((event) => {
  // note that all the below are valid ways of accessing the above mentioned variables
  useRuntimeConfig(event).helloThere
  useRuntimeConfig(event).secret
  process.env.NITRO_HELLO_THERE
  import.meta.env.SECRET
});

#Specify Variables in Development Mode

For development, you can use a .env file to specify environment variables:

NITRO_HELLO_THERE="captain"
SECRET="top-secret"

#Specify Variables for local previews

After build, when you try out your project locally with wrangler dev or wrangler pages dev, in order to have access to environment variables you will need to specify the in a .dev.vars file in the root of your project (as presented in the Pages and Workers documentation).

If you are using a .env file while developing, your .dev.vars should be identical to it.

#Specify Variables for Production

For production, use the Cloudflare dashboard or the wrangler secret command to set environment variables and secrets.

#Specify Variables using wrangler.toml/wrangler.json

You can specify a custom wrangler.toml/wrangler.json file and define vars inside.

Example:

# Shared
[vars]
NITRO_HELLO_THERE="general"
SECRET="secret"

# Override values for `--env production` usage
[env.production.vars]
NITRO_HELLO_THERE="captain"
SECRET="top-secret"

#Direct access to Cloudflare bindings

Bindings are what allows you to interact with resources from the Cloudflare platform, examples of such resources are key-value data storages (KVs) and serverless SQL databases (D1s).

In runtime, you can access bindings from the request event, by accessing its context.cloudflare.env field, this is for example how you can access a D1 bindings:

defineEventHandler(async (event) => {
  const { cloudflare } = event.context
  const stmt = await cloudflare.env.MY_D1.prepare('SELECT id FROM table')
  const { results } = await stmt.all()
})

#Dev Preset

Cloudflare preset can be enabled in development mode for production environment emulation and access to the bindings in local dev.

In order to enable dev preset, make sure using latest nitro version (>=2.12) and install wrangler as a dependency.

npm i -D wrangler

Then, update config:

export default defineNitroConfig({
    compatibilityDate: "2025-07-15", // or "latest"
    preset: "cloudflare-module" // or "cloudflare-pages"
})

In development terminal, you should see a message like this:

ℹ Using cloudflare-dev emulation in development mode.

In order to access bindings in dev mode we start by defining the bindings. You can do this in a wrangler.toml/wrangler.jsonc file, or directly in your Nitro config under cloudflare.wrangler (accepts the same type as wrangler.json).

For example to define a variable and a KV namespace in a wrangler.toml

[vars]
MY_VARIABLE="my-value"

[[kv_namespaces]]
binding = "MY_KV"
id = "xxx"

Or in your Nitro config:

export default defineNitroConfig({
    cloudflare: {
      wrangler: {
        vars: {
          MY_VARIABLE: "my-value"
        },
        kv_namespaces: [
          {
            binding: "MY_KV",
            id: "xxx"
          }
        ]
      }
    }
});

you will be able to access the MY_VARIABLE and MY_KV from the request event just as illustrated above.