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.

nitro.config.ts
import { defineNitroConfig } from "nitro/config";

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.

Additional Exports

You can add a exports.cloudflare.ts file to your project root to export additional handlers or properties to the Cloudflare Worker entrypoint.

exports.cloudflare.ts
export class MyWorkflow extends WorkflowEntrypoint {
  async run(event: WorkflowEvent, step: WorkflowStep) {
    // ...
  }
}

Nitro will automatically detect this file and include its exports in the final build.

The exports.cloudflare.ts file must not have a default export.

You can also customize the entrypoint file location using the cloudflare.exports option in your nitro.config.ts:

nitro.config.ts
export default defineConfig({
  cloudflare: {
    exports: "custom-exports-entry.ts"
  }
})

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.

nitro.config.ts
import { defineNitroConfig } from "nitro/config";

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

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:

import { defineHandler } from "nitro/h3";
import { useRuntimeConfig } from "nitro/runtime-config";

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 defineHandler((event) => {
  // note that all the below are valid ways of accessing the above mentioned variables
  useRuntimeConfig().helloThere
  useRuntimeConfig().secret
  process.env.NITRO_HELLO_THERE
  import.meta.env.SECRET
});

Specify Variables in Development Mode

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

NITRO_HELLO_THERE="captain"
SECRET="top-secret"
Note: Make sure you add .env and .env.local 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 or .env.local 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:

# 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:

import { defineHandler } from "nitro/h3";

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

Access to the bindings in local dev

To access bindings in dev mode, we first define them. You can do this in a wrangler.toml/wrangler.json 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 wrangler.toml:

[vars]
MY_VARIABLE="my-value"

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

Or in your Nitro config:

nitro.config.js
import { defineNitroConfig } from "nitro/config";

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.

Next we install the required wrangler package (if not already installed):

npm i wrangler -D

From this moment, when running

npm run dev

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.