Deploy Nitro apps to Cloudflare.
Preset: cloudflare_pages
:read-more{title="Cloudflare Pages" to="https://pages.cloudflare.com/"}
::note This is the recommended preset for Cloudflare deployments, please consider using the alternative ones only if you have special requirements or needs. ::
::note Integration with this provider is possible with zero configuration. ::
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).
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:
- By defining either the
NITRO_PRESET
or theSERVER_PRESET
environment variable set tocloudflare-pages
when running the build process, like so:
NITRO_PRESET=cloudflare-pages npm run build
- Or by updating your Nitro preset configuration:
"preset": "cloudflare-pages",
and then running the standard build command:
:pm-run{script="build"}
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:
:pm-install{name="wrangler"}
After having built your application you can preview it locally with wrangler by running:
:pm-x{command="wrangler pages dev dist"}
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:
:pm-x{command="wrangler login"}
Then you can deploy the application with:
:pm-x{command="wrangler pages deploy dist"}
Preset: cloudflare_module
::note Note: This preset uses the module worker syntax for deployment. ::
::warning Note: Using this preset is not recommended. ::
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"
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
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:
:pm-x{command="wrangler deploy"}
Preset: cloudflare
::note Note: This preset uses the service worker syntax for deployment. ::
::warning 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.
Regardless on whether you're using Cloudflare Pages or Cloudflare workers, you can use the Wrangler GitHub actions to deploy your application.
::note
Note: Remember to instruct Nitro to use the correct preset (note that this is necessary for all presets including the cloudflare_pages
one).
::
Nitro allows you to universally access environment variables using process.env
or import.meta.env
or the runtime config.
::note 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
});
For development, you can use a .env
file to specify environment variables:
NITRO_HELLO_THERE="captain"
SECRET="top-secret"
::note
Note: Make sure you add .env
to the .gitignore
file so that you don't commit it as it can contain sensitive information.
::
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
Note: Make sure you add .dev.vars
to the .gitignore
file so that you don't commit it as it can contain sensitive information.
::
For production, use the cloudflare dashboard or the wrangler secret
command to set environment variables and secrets.
You can specify a custom wrangler.toml
file and define vars inside.
::note
Note: wrangler.toml
isn't supported by cloudflare pages.
::
::warning Note that this isn't recommend for sensitive data. ::
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"
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).
::read-more For more details on Bindings and how to use them please refer to the Cloudflare Pages and Workers documentation. ::
Tip
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{title="Database Layer" to="/guide/database"}
:read-more{title="KV Storage" to="/guide/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((event) => {
const { cloudflare } = event.context
const stmt = await cloudflare.env.MY_D1.prepare('SELECT id FROM table')
const { results } = await stmt.all()
})
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.
Note
The nitro-cloudflare-dev
module is experimental. The Nitro team is looking into a more native integration which could in the near future make the module unneeded.
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"
Note
Only bindings in the default environment are recognized.
Next we install the nitro-cloudflare-dev
module as well as the required wrangler
package (if not already installed):
:pm-install{name="-D nitro-cloudflare-dev wrangler"}
Then define module:
::code-group
import nitroCloudflareBindings from "nitro-cloudflare-dev";
export default defineNitroConfig({
modules: [nitroCloudflareBindings],
});
export default defineNuxtConfig({
modules: ['nitro-cloudflare-dev']
})
::
From this moment, when running
::pm-run{script="dev"}
you will be able to access the MY_VARIABLE
and MY_KV
from the request event just as illustrated above.