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()
})

Access to the bindings in local dev

In order to access bindings in dev mode we start by defining the bindings. 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 a wrangler.toml

[vars]
MY_VARIABLE="my-value"

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

Or in your Nitro config:

import nitroCloudflareBindings from "nitro-cloudflare-dev";

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

Next we install the nitro-cloudflare-dev module as well as the required wrangler package (if not already installed):

npm i -D nitro-cloudflare-dev wrangler

Then define module:

import nitroCloudflareBindings from "nitro-cloudflare-dev";

export default defineNitroConfig({
  modules: [nitroCloudflareBindings],
});

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.