Cloudflare

Cloudflare Pages

Preset: cloudflare_pages

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).

Building your Application using the preset

The preset only applies for the application build process.

If you use the Cloudflare Pages GitHub/GitLab integration, and you don't need to preview your application locally, Nitro does not require any type of configuration. When you push to your repository, the Cloudflare Pages CI/CD process will automatically build your project and Nitro will detect the correct environment and build your application accordingly.

If instead you want preview your application locally and/or manually deploy it, when building the application you will need to let Nitro know that the target environment is the Cloudflare Pages one, you can do that in two ways:

NITRO_PRESET=cloudflare-pages npm run build

"preset": "cloudflare-pages",

and then running the standard build command:

npm run build

Wrangler

To preview your application locally or manually deploy it you will need to use the wrangler CLI tool, simply install it as a node dependency:

npm i wrangler

Preview your app locally

After having built your application you can preview it locally with wrangler by running:

npx wrangler pages dev dist

Deploy from your local machine using wrangler

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 dist

Cloudflare Module Workers

Preset: cloudflare_module

When using Workers you will need a wrangler.toml file, in your root directory.

The following shows a typical wrangler.toml file for a Nitro application:

name = "playground"
main = "./.output/server/index.mjs"
workers_dev = true
compatibility_date = "2023-12-01"
# account_id = "<(optional) your Cloudflare account id, retrievable from the Cloudflare dashboard>"
# route = "<(optional) mainly useful when you want to setup custom domains>"

rules = [
  { type = "ESModule", globs = ["**/*.js", "**/*.mjs"]},
]

[site]
bucket = ".output/public"

Preview your app locally

You can use wrangler, to preview your app locally:

NITRO_PRESET=cloudflare npm run build

# If you have added a 'wrangler.toml' file like above in the root of your project:
npx wrangler dev

# If you don't have a 'wrangler.toml', directly use:
npx wrangler dev .output/server/index.mjs --site .output/public

Deploy from your local machine using wrangler

Install wrangler and login to your Cloudflare account:

npm i wrangler
wrangler login

Generate your app using the cloudflare preset:

NITRO_PRESET=cloudflare_module npm run build

You can then preview it locally:

# If you have a 'wrangler.toml' like above:
npx wrangler dev

# If you don't have a 'wrangler.toml':
npx wrangler dev .output/server/index.mjs --site .output/public

and publish it:

npx wrangler 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

You can specify a custom wrangler.toml 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((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 env

In order to access bindings during local dev mode, regardless of the chosen preset, it is recommended to use a wrangler.toml file (as well as a .dev.vars one) in combination with the nitro-cloudflare-dev module as illustrated below.

In order to access bindings in dev mode we start by defining the bindings in a wrangler.toml file, this is for example how you would define a variable and a KV namespace:

[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