Nitro logoNitro

Cloudflare

Deploy Nitro apps to Cloudflare.

Cloudflare Workers

Preset: cloudflare_module

Read more in Cloudflare Workers.
Integration with this provider is possible with zero configuration supporting workers builds (beta).
To use Workers with Static Assets, you need a Nitro compatibility date set to 2024-09-19 or later.

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.

Read more in Guide > Plugins#nitro Runtime Hooks.

Cloudflare Pages

Preset: cloudflare_pages

Read more in Cloudflare Pages.
Integration with this provider is possible with zero configuration.
Cloudflare Workers Module is the new recommended preset for deployments. Please consider using the pages only if you need specific features.

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

Note: This preset uses the service worker syntax for deployment.
Note: This preset is deprecated.

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.

Note: Remember to instruct Nitro to use the correct preset (note that this is necessary for all presets including the cloudflare_pages one).

Environment Variables

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

Make sure to only access environment variables within the event lifecycle and not in global contexts since Cloudflare only makes them available during the request lifecycle and not before.

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"
Note: Make sure you add .env to the .gitignore file so that you don't commit it as it can contain sensitive information.

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.

Note: Make sure you add .dev.vars to the .gitignore file so that you don't commit it as it can contain sensitive information.

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.

Note that this isn't recommend for sensitive data like secrets.

Example:

wrangler.toml
# 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).

For more details on Bindings and how to use them please refer to the Cloudflare Pages and Workers documentation.
Nitro provides high level API to interact with primitives such as KV Storage and Database and you are highly recommended to prefer using them instead of directly depending on low-level APIs for usage stability.
Read more in Database Layer.
Read more in KV Storage.

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

wrangler.toml
[vars]
MY_VARIABLE="my-value"

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

Or in your Nitro config:

nitro.config.js
export default defineNitroConfig({
    cloudflare: {
      wrangler: {
        vars: {
          MY_VARIABLE: "my-value"
        },
        kv_namespaces: [
          {
            binding: "MY_KV",
            id: "xxx"
          }
        ]
      }
    }
});
Only bindings in the default environment are recognized.

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

Cleavr

Deploy Nitro apps to Cleavr.

Deno Deploy

Deploy Nitro apps to Deno Deploy.