Configuration (10)

Last updated Jun 25, 2026 Caution

If your project contains an existing Wrangler file that you previously used for local development, make sure you verify that it matches your project settings in the Cloudflare dashboard before opting-in to deploy your Pages project with the Wrangler configuration file. Instead of writing your Wrangler file by hand, Cloudflare recommends using npx wrangler pages download config to download your current project settings into a Wrangler file.

Note

As of Wrangler v3.91.0, Wrangler supports both JSON (wrangler.json or wrangler.jsonc) and TOML (wrangler.toml) for its configuration file. Prior to that version, only wrangler.toml was supported.

Pages Functions can be configured two ways, either via the Cloudflare dashboard ↗︎ or the Wrangler configuration file, a file used to customize the development and deployment setup for Workers and Pages Functions.

This page serves as a reference on how to configure your Pages project via the Wrangler configuration file.

If using a Wrangler configuration file, you must treat your file as the source of truth for your Pages project configuration.

Using the Wrangler configuration file to configure your Pages project allows you to:

• Store your configuration file in source control: Keep your configuration in your repository alongside the rest of your code.
• Edit your configuration via your code editor: Remove the need to switch back and forth between interfaces.
• Write configuration that is shared across environments: Define configuration like bindings for local development, preview and production in one file.
• Ensure better access control: By using a configuration file in your project repository, you can control who has access to make changes without giving access to your Cloudflare dashboard.

Example Wrangler file

{
    "$schema": "./node_modules/wrangler/config-schema.json",
    "name": "my-pages-app",
    "pages_build_output_dir": "./dist",
    "kv_namespaces": [
        {
            "binding": "KV",
            "id": "<NAMESPACE_ID>"
        }
    ],
    "d1_databases": [
        {
            "binding": "DB",
            "database_name": "northwind-demo",
            "database_id": "<DATABASE_ID>"
        }
    ],
    "vars": {
        "API_KEY": "1234567asdf"
    }
}

"$schema" = "./node_modules/wrangler/config-schema.json"
name = "my-pages-app"
pages_build_output_dir = "./dist"

[[kv_namespaces]]
binding = "KV"
id = "<NAMESPACE_ID>"

[[d1_databases]]
binding = "DB"
database_name = "northwind-demo"
database_id = "<DATABASE_ID>"

[vars]
API_KEY = "1234567asdf"

Requirements

V2 build system

Pages Functions configuration via the Wrangler configuration file requires the V2 build system or later. To update from V1, refer to the V2 build system migration instructions.

Wrangler

You must have Wrangler version 3.45.0 or higher to use a Wrangler configuration file for your Pages project's configuration. To check your Wrangler version, update Wrangler or install Wrangler, refer to Install/Update Wrangler.

Migrate from dashboard configuration

The migration instructions for Pages projects that do not have a Wrangler file currently are different than those for Pages projects with an existing Wrangler file. Read the instructions based on your situation carefully to avoid errors in production.

Projects with existing Wrangler file

Before you could use the Wrangler configuration file to define your preview and production configuration, it was possible to use the file to define which bindings should be available to your Pages project in local development.

If you have been using a Wrangler configuration file for local development, you may already have a file in your Pages project that looks like this:

{
    "kv_namespaces": [
        {
            "binding": "KV",
            "id": "<NAMESPACE_ID>"
        }
    ]
}

[[kv_namespaces]]
binding = "KV"
id = "<NAMESPACE_ID>"

If you would like to use your existing Wrangler file for your Pages project configuration, you must:

1. Add the pages_build_output_dir key with the appropriate value of your build output directory (for example, pages_build_output_dir = "./dist".)
2. Review your existing Wrangler configuration carefully to make sure it aligns with your desired project configuration before deploying.

If you add the pages_build_output_dir key to your Wrangler configuration file and deploy your Pages project, Pages will use whatever configuration was defined for local use, which is very likely to be non-production. Do not deploy until you are confident that your Wrangler configuration file is ready for production use.

Overwriting configuration

Running wrangler pages download config will overwrite your existing Wrangler file with a generated Wrangler file based on your Cloudflare dashboard configuration. Run this command only if you want to discard your previous Wrangler file that you used for local development and start over with configuration pulled from the Cloudflare dashboard.

You can continue to use your Wrangler file for local development without migrating it for production use by not adding a pages_build_output_dir key. If you do not add a pages_build_output_dir key and run wrangler pages deploy, you will see a warning message telling you that fields are missing and that the file will continue to be used for local development only.

Projects without existing Wrangler file

If you have an existing Pages project with configuration set up via the Cloudflare dashboard and do not have an existing Wrangler file in your Project, run the wrangler pages download config command in your Pages project directory. The wrangler pages download config command will download your existing Cloudflare dashboard configuration and generate a valid Wrangler file in your Pages project directory.

npx wrangler pages download config <PROJECT_NAME>

yarn wrangler pages download config <PROJECT_NAME>

pnpm wrangler pages download config <PROJECT_NAME>

Review your generated Wrangler file. To start using the Wrangler configuration file for your Pages project's configuration, create a new deployment, via Git integration or Direct Upload.

Handling compatibility dates set to "Latest"

In the Cloudflare dashboard, you can set compatibility dates for preview deployments to "Latest". This will ensure your project is always using the latest compatibility date without the need to explicitly set it yourself.

If you download a Wrangler configuration file from a project configured with "Latest" using the wrangler pages download command, your Wrangler configuration file will have the latest compatibility date available at the time you downloaded the configuration file. Wrangler does not support the "Latest" functionality like the dashboard. Compatibility dates must be explicitly set when using a Wrangler configuration file.

Refer to this guide for more information on what compatibility dates are and how they work.

Differences using a Wrangler configuration file for Pages Functions and Workers

If you have used Workers, you may already be familiar with the Wrangler configuration file. There are a few key differences to be aware of when using this file with your Pages Functions project:

• The configuration fields do not match exactly between Pages Functions Wrangler file and the Workers equivalent. For example, configuration keys like main, which are Workers specific, do not apply to a Pages Function's Wrangler configuration file. Some functionality supported by Workers, such as module aliasing cannot yet be used by Cloudflare Pages projects.
• The Pages' Wrangler configuration file introduces a new key, pages_build_output_dir, which is only used for Pages projects.
• The concept of environments and configuration inheritance in this file is not the same as Workers.
• This file becomes the source of truth when used, meaning that you can not edit the same fields in the dashboard once you are using this file.

Configure environments

With a Wrangler configuration file, you can quickly set configuration across your local environment, preview deployments, and production.

Local development

The Wrangler configuration file applies locally when using wrangler pages dev. This means that you can test out configuration changes quickly without a need to login to the Cloudflare dashboard. Refer to the following config file for an example:

{
    "$schema": "./node_modules/wrangler/config-schema.json",
    "name": "my-pages-app",
    "pages_build_output_dir": "./dist",
    // Set this to today's date
    "compatibility_date": "2026-10-27",
    "compatibility_flags": [
        "nodejs_compat"
    ],
    "kv_namespaces": [
        {
            "binding": "KV",
            "id": "<NAMESPACE_ID>"
        }
    ]
}

"$schema" = "./node_modules/wrangler/config-schema.json"
name = "my-pages-app"
pages_build_output_dir = "./dist"
# Set this to today's date
compatibility_date = "2026-10-27"
compatibility_flags = [ "nodejs_compat" ]

[[kv_namespaces]]
binding = "KV"
id = "<NAMESPACE_ID>"

This Wrangler configuration file adds the nodejs_compat compatibility flag and a KV namespace binding to your Pages project. Running wrangler pages dev in a Pages project directory with this Wrangler configuration file will apply the nodejs_compat compatibility flag locally, and expose the KV binding in your Pages Function code at context.env.KV.

Note

For a full list of configuration keys, refer to inheritable keys and non-inheritable keys.

Production and preview deployments

Once you are ready to deploy your project, you can set the configuration for production and preview deployments by creating a new deployment containing a Wrangler file.

Note

For the following commands, if you are using git it is important to remember the branch that you set as your production branch as well as your preview branch settings.

To use the example above as your configuration for production, make a new production deployment using:

npx wrangler pages deploy

or more specifically:

npx wrangler pages deploy --branch <PRODUCTION BRANCH>

To deploy the configuration for preview deployments, you can run the same command as above while on a branch you have configured to work with preview deployments. This will set the configuration for all preview deployments, not just the deployments from a specific branch. Pages does not currently support branch-based configuration.

Note

The --branch flag is optional with wrangler pages deploy. If you use git integration, Wrangler will infer the branch you are on from the repository you are currently in and implicitly add it to the command.

Environment-specific overrides

There are times that you might want to use different configuration across local, preview deployments, and production. It is possible to override configuration for production and preview deployments by using [env.production] or [env.preview].

Note

Unlike Workers Environments, production and preview are the only two options available via [env.<ENVIRONMENT>].

Refer to the following Wrangler configuration file for an example of how to override preview deployment configuration:

{
    "$schema": "./node_modules/wrangler/config-schema.json",
    "name": "my-pages-site",
    "pages_build_output_dir": "./dist",
    "kv_namespaces": [
        {
            "binding": "KV",
            "id": "<NAMESPACE_ID>"
        }
    ],
    "vars": {
        "API_KEY": "1234567asdf"
    },
    "env": {
        "preview": {
            "kv_namespaces": [
                {
                    "binding": "KV",
                    "id": "<PREVIEW_NAMESPACE_ID>"
                }
            ],
            "vars": {
                "API_KEY": "8901234bfgd"
            }
        }
    }
}

"$schema" = "./node_modules/wrangler/config-schema.json"
name = "my-pages-site"
pages_build_output_dir = "./dist"

[[kv_namespaces]]
binding = "KV"
id = "<NAMESPACE_ID>"

[vars]
API_KEY = "1234567asdf"

[[env.preview.kv_namespaces]]
binding = "KV"
id = "<PREVIEW_NAMESPACE_ID>"

[env.preview.vars]
API_KEY = "8901234bfgd"

If you deployed this file via wrangler pages deploy, name, pages_build_output_dir, kv_namespaces, and vars would apply the configuration to local and production, while env.preview would override kv_namespaces and vars for preview deployments.

If you wanted to have configuration values apply to local and preview, but override production, your file would look like this:

{
    "$schema": "./node_modules/wrangler/config-schema.json",
    "name": "my-pages-site",
    "pages_build_output_dir": "./dist",
    "kv_namespaces": [
        {
            "binding": "KV",
            "id": "<NAMESPACE_ID>"
        }
    ],
    "vars": {
        "API_KEY": "1234567asdf"
    },
    "env": {
        "production": {
            "kv_namespaces": [
                {
                    "binding": "KV",
                    "id": "<PRODUCTION_NAMESPACE_ID>"
                }
            ],
            "vars": {
                "API_KEY": "8901234bfgd"
            }
        }
    }
}

"$schema" = "./node_modules/wrangler/config-schema.json"
name = "my-pages-site"
pages_build_output_dir = "./dist"

[[kv_namespaces]]
binding = "KV"
id = "<NAMESPACE_ID>"

[vars]
API_KEY = "1234567asdf"

[[env.production.kv_namespaces]]
binding = "KV"
id = "<PRODUCTION_NAMESPACE_ID>"

[env.production.vars]
API_KEY = "8901234bfgd"

You can always be explicit and override both preview and production:

{
    "$schema": "./node_modules/wrangler/config-schema.json",
    "name": "my-pages-site",
    "pages_build_output_dir": "./dist",
    "kv_namespaces": [
        {
            "binding": "KV",
            "id": "<NAMESPACE_ID>"
        }
    ],
    "vars": {
        "API_KEY": "1234567asdf"
    },
    "env": {
        "preview": {
            "kv_namespaces": [
                {
                    "binding": "KV",
                    "id": "<PREVIEW_NAMESPACE_ID>"
                }
            ],
            "vars": {
                "API_KEY": "8901234bfgd"
            }
        },
        "production": {
            "kv_namespaces": [
                {
                    "binding": "KV",
                    "id": "<PRODUCTION_NAMESPACE_ID>"
                }
            ],
            "vars": {
                "API_KEY": "6567875fvgt"
            }
        }
    }
}

"$schema" = "./node_modules/wrangler/config-schema.json"
name = "my-pages-site"
pages_build_output_dir = "./dist"

[[kv_namespaces]]
binding = "KV"
id = "<NAMESPACE_ID>"

[vars]
API_KEY = "1234567asdf"

[[env.preview.kv_namespaces]]
binding = "KV"
id = "<PREVIEW_NAMESPACE_ID>"

[env.preview.vars]
API_KEY = "8901234bfgd"

[[env.production.kv_namespaces]]
binding = "KV"
id = "<PRODUCTION_NAMESPACE_ID>"

[env.production.vars]
API_KEY = "6567875fvgt"

Inheritable keys

Inheritable keys are configurable at the top-level, and can be inherited (or overridden) by environment-specific configuration.