Cloudflare Docs
Pages
Cloudflare Docs
Pages
GitHub icon
Edit this page on GitHub
Set theme to dark (⇧+D)
  1. Products
  2. Pages
  3. Functions
  4. Bindings

Bindings

A binding enables your Pages Functions to interact with resources on the Cloudflare developer platform. Use bindings to integrate your Pages Functions with Cloudflare resources like KV, Durable Objects, R2, and D1. You can set bindings for both production and preview environments.

This guide will instruct you on configuring a binding for your Pages Function. You must already have a Cloudflare Developer Platform resource set up to continue.

​​ KV namespaces

Workers KV is Cloudflare’s key-value storage solution.

To bind your KV namespace to your Pages Function, you can configure a KV namespace binding in wrangler.toml or the Cloudflare dashboard.

To configure a KV namespace binding via the Cloudflare dashboard:

  1. Log in to the Cloudflare dashboard and select your account.
  2. In Account Home, select Workers & Pages.
  3. Select your Pages project > Settings > Functions > KV namespace bindings > Add binding.
  4. Choose whether you would like to set up the binding in your Production or Preview environment.
  5. Give your binding a name under Variable name.
  6. Under KV namespace, select your desired namespace. You must repeat steps 5 and 6 for both the Production and Preview environments.
  7. Redeploy your project for the binding to take effect.

Below is an example of how to use KV in your Function. In the following example, your KV namespace binding is called TODO_LIST and you can access the binding in your Function code on context.env:

export async function onRequest(context) {
  const task = await context.env.TODO_LIST.get("Task:123");
  return new Response(task);

}

interface Env {
  TODO_LIST: KVNamespace;

}



export const onRequest: PagesFunction<Env> = async (context) => {
  const task = await context.env.TODO_LIST.get("Task:123");
  return new Response(task);

}

​​ Interact with your KV namespaces locally

You can interact with your KV namespace bindings locally in one of two ways:

  • Configure your Pages project’s wrangler.toml file and run npx wrangler pages dev.
  • Pass arguments to wrangler pages dev directly.

To interact with your KV namespace binding locally by passing arguments to the Wrangler CLI, add -k <BINDING_NAME> or --kv=<BINDING_NAME> to the wrangler pages dev command. For example, if your KV namespace is bound your Function via the TODO_LIST binding, access the KV namespace in local development by running:

$ npx wrangler pages dev <OUTPUT_DIR> --kv=TODO_LIST

​​ Durable Objects

Durable Objects (DO) are Cloudflare’s strongly consistent data store that power capabilities such as connecting WebSockets and handling state.

You must create a Durable Object Worker and bind it to your Pages project using the Cloudflare dashboard or your Pages project’s wrangler.toml. You cannot create and deploy a Durable Object within a Pages project.

To bind your Durable Object to your Pages Function, you can configure a Durable Object binding in wrangler.toml or the Cloudflare dashboard.

To configure a Durable Object binding via the Cloudflare dashboard:

  1. Log in to the Cloudflare dashboard and select your account.
  2. In Account Home, select Workers & Pages.
  3. Select your Pages project > Settings > Functions > Durable Object bindings > Add binding.
  4. Choose whether you would like to set up the binding in your Production or Preview environment.
  5. Give your binding a name under Variable name.
  6. Under Durable Object namespace, select your desired namespace. You must repeat steps 5 and 6 for both the Production and Preview environments.
  7. Redeploy your project for the binding to take effect.

Below is an example of how to use Durable Objects in your Function. In the following example, your DO binding is called DURABLE_OBJECT and you can access the binding in your Function code on context.env:

export async function onRequestGet(context) {
  const id = context.env.DURABLE_OBJECT.newUniqueId();
  const stub = context.env.DURABLE_OBJECT.get(id);


  // Pass the request down to the durable object
  return stub.fetch(context.request);

}

interface Env {
  DURABLE_OBJECT: DurableObjectNamespace;

}



export const onRequestGet: PagesFunction<Env> = async (context) => {
  const id = context.env.DURABLE_OBJECT.newUniqueId();
  const stub = context.env.DURABLE_OBJECT.get(id);


  // Pass the request down to the durable object
  return stub.fetch(context.request);

}

​​ Interact with your Durable Object namespaces locally

You can interact with your Durable Object bindings locally in one of two ways:

  • Configure your Pages project’s wrangler.toml file and run npx wrangler pages dev.
  • Pass arguments to wrangler pages dev directly.

While developing locally, to interact with a Durable Object namespace, run wrangler dev in the directory of the Worker exporting the Durable Object. In another terminal, run wrangler pages dev in the directory of your Pages project.

To interact with your Durable Object namespace locally via the Wrangler CLI, append --do <BINDING_NAME>=<CLASS_NAME>@<SCRIPT_NAME> to wrangler pages dev. CLASS_NAME indicates the Durable Object class name and SCRIPT_NAME the name of your Worker.

For example, if your Worker is called do-worker and it declares a Durable Object class called DurableObjectExample, access this Durable Object by running npx wrangler dev in the do-worker directory. At the same time, run npx wrangler pages dev <OUTPUT_DIR> --do MY_DO=DurableObjectExample@do-worker in your Pages’ project directory. Interact with the MY_DO binding in your Function code by using context.env (for example, context.env.MY_DO).

​​ R2 buckets

R2 is Cloudflare’s blob storage solution that allows developers to store large amounts of unstructured data without the egress fees.

To bind your R2 bucket to your Pages Function, you can configure a R2 bucket binding in wrangler.toml or the Cloudflare dashboard.

To configure a R2 bucket binding via the Cloudflare dashboard:

  1. Log in to the Cloudflare dashboard and select your account.
  2. In Account Home, select Workers & Pages.
  3. Select your Pages project > Settings > Functions > R2 bucket bindings > Add binding.
  4. Choose whether you would like to set up the binding in your Production or Preview environment.
  5. Give your binding a name under Variable name.
  6. Under R2 bucket, select your desired R2 bucket. You must repeat steps 5 and 6 for both the Production and Preview environments.
  7. Redeploy your project for the binding to take effect.

Below is an example of how to use R2 buckets in your Function. In the following example, your R2 bucket binding is called BUCKET and you can access the binding in your Function code on context.env:

export async function onRequest(context) {
  const obj = await context.env.BUCKET.get('some-key');
  if (obj === null) {
    return new Response('Not found', { status: 404 });
  }
  return new Response(obj.body);

}

interface Env {
  BUCKET: R2Bucket;

}



export const onRequest: PagesFunction<Env> = async (context) => {
  const obj = await context.env.BUCKET.get('some-key');
  if (obj === null) {
    return new Response('Not found', { status: 404 });
  }
  return new Response(obj.body);

}

​​ Interact with your R2 buckets locally

You can interact with your R2 bucket bindings locally in one of two ways:

  • Configure your Pages project’s wrangler.toml file and run npx wrangler pages dev.
  • Pass arguments to wrangler pages dev directly.

To interact with an R2 bucket locally via the Wrangler CLI, add --r2=<BINDING_NAME> to the wrangler pages dev command. If your R2 bucket is bound to your Function with the BUCKET binding, access this R2 bucket in local development by running:

$ npx wrangler pages dev <OUTPUT_DIR> --r2=BUCKET

Interact with this binding by using context.env (for example, context.env.BUCKET.)

​​ D1 databases

D1 is Cloudflare’s native serverless database.

To bind your D1 database to your Pages Function, you can configure a D1 database binding in wrangler.toml or the Cloudflare dashboard.

To configure a D1 database binding via the Cloudflare dashboard:

  1. Log in to the Cloudflare dashboard and select your account.
  2. In Account Home, select Workers & Pages.
  3. Select your Pages project > Settings > Functions > D1 database bindings > Add binding.
  4. Choose whether you would like to set up the binding in your Production or Preview environment.
  5. Give your binding a name under Variable name.
  6. Under D1 database, select your desired D1 database. You must repeat steps 5 and 6 for both the Production and Preview environments.
  7. Redeploy your project for the binding to take effect.

Below is an example of how to use D1 in your Function. In the following example, your D1 database binding is NORTHWIND_DB and you can access the binding in your Function code on context.env:

export async function onRequest(context) {
  // Create a prepared statement with our query
  const ps = context.env.NORTHWIND_DB.prepare('SELECT * from users');
  const data = await ps.first();


  return Response.json(data);

}

interface Env {
  NORTHWIND_DB: D1Database;

}



export const onRequest: PagesFunction<Env> = async (context) => {
  // Create a prepared statement with our query
  const ps = context.env.NORTHWIND_DB.prepare('SELECT * from users');
  const data = await ps.first();


  return Response.json(data);

}

​​ Interact with your D1 databases locally

You can interact with your D1 database bindings locally in one of two ways:

  • Configure your Pages project’s wrangler.toml file and run npx wrangler pages dev.
  • Pass arguments to wrangler pages dev directly.

To interact with a D1 database via the Wrangler CLI while developing locally, add --d1 <BINDING_NAME>=<DATABASE_ID> to the wrangler pages dev command.

If your D1 database is bound to your Pages Function via the NORTHWIND_DB binding and the database_id in your wrangler.toml file is xxxx-xxxx-xxxx-xxxx-xxxx, access this database in local development by running:

$ npx wrangler pages dev <OUTPUT_DIR> --d1 NORTHWIND_DB=xxxx-xxxx-xxxx-xxxx-xxxx

Interact with this binding by using context.env (for example, context.env.NORTHWIND_DB.)

Refer to the D1 client API documentation for the API methods available on your D1 binding.

​​ Vectorize indexes

Vectorize is Cloudflare’s native vector database.

To bind your Vectorize index to your Pages Function, you can configure a Vectorize index binding in wrangler.toml or the Cloudflare dashboard.

To configure a Vectorize index binding via the Cloudflare dashboard:

  1. Log in to the Cloudflare dashboard and select your account.
  2. In Account Home, select Workers & Pages.
  3. Choose whether you would like to set up the binding in your Production or Preview environment.
  4. Select your Pages project > Settings > Functions > Vectorize index bindings > Add binding.
  5. Give your binding a name under Variable name.
  6. Under Vectorize index, select your desired Vectorize index. You must repeat steps 5 and 6 for both the Production and Preview environments.
  7. Redeploy your project for the binding to take effect.

​​ Use Vectorize index bindings

To use Vectorize index in your Pages Function, you can access your Vectorize index binding in your Pages Function code. In the following example, your Vectorize index binding is called VECTORIZE_INDEX and you can access the binding in your Pages Function code on context.env.

// Sample vectors: 3 dimensions wide.

//

// Vectors from a machine-learning model are typically ~100 to 1536 dimensions

// wide (or wider still).

const sampleVectors = [
	{ id: '1', values: [32.4, 74.1, 3.2], metadata: { url: '/products/sku/13913913' } },
	{ id: '2', values: [15.1, 19.2, 15.8], metadata: { url: '/products/sku/10148191' } },
	{ id: '3', values: [0.16, 1.2, 3.8], metadata: { url: '/products/sku/97913813' } },
	{ id: '4', values: [75.1, 67.1, 29.9], metadata: { url: '/products/sku/418313' } },
	{ id: '5', values: [58.8, 6.7, 3.4], metadata: { url: '/products/sku/55519183' } },

];



export async function onRequest(context) {
  let path = new URL(context.request.url).pathname;
  if (path.startsWith("/favicon")) {
    return new Response('', { status: 404 });
  }


  // You only need to insert vectors into your index once
  if (path.startsWith("/insert")) {
    // Insert some sample vectors into your index
    // In a real application, these vectors would be the output of a machine learning (ML) model,
    // such as Workers AI, OpenAI, or Cohere.
    let inserted = await context.env.VECTORIZE_INDEX.insert(sampleVectors);


    // Return the number of IDs we successfully inserted
    return Response.json(inserted);
  }

}

export interface Env {
	// This makes our vector index methods available on context.env.VECTORIZE_INDEX.*
	// For example, context.env.VECTORIZE_INDEX.insert() or query()
	VECTORIZE_INDEX: VectorizeIndex;

}



// Sample vectors: 3 dimensions wide.

//

// Vectors from a machine-learning model are typically ~100 to 1536 dimensions

// wide (or wider still).

const sampleVectors: Array<VectorizeVector> = [
	{ id: '1', values: [32.4, 74.1, 3.2], metadata: { url: '/products/sku/13913913' } },
	{ id: '2', values: [15.1, 19.2, 15.8], metadata: { url: '/products/sku/10148191' } },
	{ id: '3', values: [0.16, 1.2, 3.8], metadata: { url: '/products/sku/97913813' } },
	{ id: '4', values: [75.1, 67.1, 29.9], metadata: { url: '/products/sku/418313' } },
	{ id: '5', values: [58.8, 6.7, 3.4], metadata: { url: '/products/sku/55519183' } },

];



export const onRequest: PagesFunction<Env> = async (context) => {
  let path = new URL(context.request.url).pathname;
  if (path.startsWith("/favicon")) {
    return new Response('', { status: 404 });
  }


  // You only need to insert vectors into your index once
  if (path.startsWith("/insert")) {
    // Insert some sample vectors into your index
    // In a real application, these vectors would be the output of a machine learning (ML) model,
    // such as Workers AI, OpenAI, or Cohere.
    let inserted = await context.env.VECTORIZE_INDEX.insert(sampleVectors);


    // Return the number of IDs we successfully inserted
    return Response.json(inserted);
  }

}

​​ Workers AI

Workers AI allows you to run machine learning models, powered by serverless GPUs, on Cloudflare’s global network.

To bind Workers AI to your Pages Function, you can configure a Workers AI binding in wrangler.toml or the Cloudflare dashboard.

When developing locally using Wrangler, you can define an AI binding using the --ai flag. Start Wrangler in development mode by running wrangler pages dev --ai AI to expose the context.env.AI binding.

To configure a Workers AI binding via the Cloudflare dashboard:

  1. Log in to the Cloudflare dashboard and select your account.
  2. In Account Home, select Workers & Pages.
  3. Select your Pages project > Settings > Functions > Workers AI bindings > Add binding.
  4. Choose whether you would like to set up the binding in your Production or Preview environment.
  5. Give your binding a name under Variable name.
  6. Redeploy your project for the binding to take effect.

​​ Use Workers AI bindings

To use Workers AI in your Pages Function, you can access your Workers AI binding in your Pages Function code. In the following example, your Workers AI binding is called AI and you can access the binding in your Pages Function code on context.env.

export async function onRequest(context) {
  const input = { prompt: "What is the origin of the phrase Hello, World" }


  const answer = await context.env.AI.run('@cf/meta/llama-2-7b-chat-int8', input);


  return Response.json(answer);

}

interface Env {
  AI: any;

}



export const onRequest: PagesFunction<Env> = async (context) => {
  const input = { prompt: "What is the origin of the phrase Hello, World" }


  const answer = await context.env.AI.run('@cf/meta/llama-2-7b-chat-int8', input)


  return Response.json(answer);

}

​​ Interact with your Workers AI binding locally

You can interact with your Workers AI bindings locally in one of two ways:

  • Configure your Pages project’s wrangler.toml file and run npx wrangler pages dev.
  • Pass arguments to wrangler pages dev directly.

To interact with a Workers AI binding via the Wrangler CLI while developing locally, run:

$ npx wrangler pages dev --ai=<BINDING_NAME>

​​ Service bindings

Service bindings enable you to call a Worker from within your Pages Function.

To bind your Pages Function to a Worker, configure a Service binding in your Pages Function using wrangler.toml or the Cloudflare dashboard.

To configure a Service binding via the Cloudflare dashboard:

  1. Log in to the Cloudflare dashboard and select your account.
  2. In Account Home, select Workers & Pages.
  3. Select your Pages project > Settings > Functions > Service bindings > Add binding.
  4. Choose whether you would like to set up the binding in your Production or Preview environment.
  5. Give your binding a name under Variable name.
  6. Under Service, select your desired Worker. You must repeat steps 5 and 6 for both the Production and Preview environments.
  7. Redeploy your project for the binding to take effect.

Below is an example of how to use Service bindings in your Function. In the following example, your Service binding is called SERVICE and you can access the binding in your Function code on context.env:

export async function onRequestGet(context) {
  return context.env.SERVICE.fetch(context.request);

}

interface Env {
  SERVICE: Fetcher;

}



export const onRequest: PagesFunction<Env> = async (context) => {
  return context.env.SERVICE.fetch(context.request);

}

​​ Interact with your Service bindings locally

You can interact with your Service bindings locally in one of two ways:

  • Configure your Pages project’s wrangler.toml file and run npx wrangler pages dev.
  • Pass arguments to wrangler pages dev directly.

To interact with a Service binding while developing locally, run the Worker you want to bind to via wrangler dev and in parallel, run wrangler pages dev with --service <BINDING_NAME>=<SCRIPT_NAME> where SCRIPT_NAME indicates the name of the Worker. For example, if your Worker is called my-worker, connect with this Worker by running it via npx wrangler dev (in the Worker’s directory) alongside npx wrangler pages dev <OUTPUT_DIR> --service MY_SERVICE=my-worker (in the Pages’ directory). Interact with this binding by using context.env (for example, context.env.MY_SERVICE).

If you set up the Service binding via the Cloudflare dashboard, you will need to append wrangler pages dev with --service <BINDING_NAME>=<SCRIPT_NAME> where BINDING_NAME is the name of the Service binding and SCRIPT_NAME is the name of the Worker.

For example, to develop locally, if your Worker is called my-worker, run npx wrangler dev in the my-worker directory. In a different terminal, also run npx wrangler pages dev <OUTPUT_DIR> --service MY_SERVICE=my-worker in your Pages project directory. Interact with this Service binding by using context.env (for example, context.env.MY_SERVICE).

​​ Queue Producers

Queue Producers enable you to send messages into a queue within your Pages Function.

To bind a queue to your Pages Function, configure a queue producer binding in your Pages Function using wrangler.toml or the Cloudflare dashboard:

To configure a queue producer binding via the Cloudflare dashboard:

  1. Log in to the Cloudflare dashboard and select your account.
  2. In Account Home, select Workers & Pages.
  3. Select your Pages project > Settings > Functions > Queue Producers bindings > Add binding.
  4. Choose whether you would like to set up the binding in your Production or Preview environment.
  5. Give your binding a name under Variable name.
  6. Under Dataset, input your desired dataset. You must repeat steps 5 and 6 for both the Production and Preview environments.
  7. Redeploy your project for the binding to take effect.

Below is an example of how to use a queue producer binding in your Function. In this example, the binding is named MY_QUEUE and you can access the binding in your Function code on context.env::

export async function onRequest(context) {
  await context.env.MY_QUEUE.send({
    url: request.url,
    method: request.method,
    headers: Object.fromEntries(request.headers),
  });


  return new Response('Sent!');

}

interface Env {
  MY_QUEUE: Queue<any>;

}



export const onRequest: PagesFunction<Env> = async (context) => {
  await context.env.MY_QUEUE.send({
    url: request.url,
    method: request.method,
    headers: Object.fromEntries(request.headers),
  });


  return new Response('Sent!');

}

​​ Interact with your Queue Producer binding locally

If using a queue producer binding with a Pages Function, you will be able to send events to a queue locally. However, it is not possible to consume events from a queue with a Pages Function. You will have to create a separate consumer Worker with a queue consumer handler to consume events from the queue. Wrangler does not yet support running separate producer Functions and consumer Workers bound to the same queue locally.

​​ Analytics Engine

The Analytics Engine binding enables you to write analytics within your Pages Function.

To bind an Analytics Engine dataset to your Pages Function, you must configure an Analytics Engine binding using wrangler.toml or the Cloudflare dashboard:

To configure an Analytics Engine binding via the Cloudflare dashboard:

  1. Log in to the Cloudflare dashboard and select your account.
  2. In Account Home, select Workers & Pages.
  3. Select your Pages project > Settings > Functions > Analytics Engine bindings > Add binding.
  4. Choose whether you would like to set up the binding in your Production or Preview environment.
  5. Give your binding a name under Variable name.
  6. Under Dataset, input your desired dataset. You must repeat steps 5 and 6 for both the Production and Preview environments.
  7. Redeploy your project for the binding to take effect.

Below is an example of how to use an Analytics Engine binding in your Function. In the following example, the binding is called ANALYTICS_ENGINE and you can access the binding in your Function code on context.env:

export async function onRequest(context) {
  const url = new URL(context.request.url);


  context.env.ANALYTICS_ENGINE.writeDataPoint({
    indexes: [],
    blobs: [url.hostname, url.pathname],
    doubles: [],
  });


  return new Response('Logged analytic');

}

interface Env {
  ANALYTICS_ENGINE: AnalyticsEngineDataset;

}



export const onRequest: PagesFunction<Env> = async (context) => {
  const url = new URL(context.request.url);


  context.env.ANALYTICS_ENGINE.writeDataPoint({
    indexes: [],
    blobs: [url.hostname, url.pathname],
    doubles: [],
  });


  return new Response('Logged analytic');

}

​​ Interact with your Analytics Engine binding locally

You cannot use an Analytics Engine binding locally.

​​ Environment variables

An environment variable is an injected value that can be accessed by your Functions. Environment variables are a type of binding that allow you to attach text strings or JSON values to your Pages Function. It is stored as plain text. Set your environment variables directly within the Cloudflare dashboard for both your production and preview environments at runtime and build-time.

To add environment variables to your Pages project, you can use wrangler.toml or the Cloudflare dashboard.

To configure an environment variable via the Cloudflare dashboard:

  1. Log in to the Cloudflare dashboard and select your account.
  2. In Account Home, select Workers & Pages.
  3. Select your Pages project > Settings > Environment variables.
  4. Selecting Add variables under Production and/or Preview.
  5. After setting a variable name and value, select Save.

Below is an example of how to use environment variables in your Function. The environment variable in this example is ENVIRONMENT and you can access the environment variable on context.env:

export function onRequest(context) {
	if (context.env.ENVIRONMENT === 'development') {
		return new Response('This is a local environment!');
	} else {
		return new Response('This is a live environment');
	}

}

interface Env {
  ENVIRONMENT: string;

}



export const onRequest: PagesFunction<Env> = async (context) => {
	if (context.env.ENVIRONMENT === 'development') {
		return new Response('This is a local environment!');
	} else {
		return new Response('This is a live environment');
	}

}

​​ Interact with your environment variables locally

You can interact with your environment variables locally in one of two ways:

  • Configure your Pages project’s wrangler.toml file and running npx wrangler pages dev.
  • Pass arguments to wrangler pages dev directly.

To interact with your environment variables locally via the Wrangler CLI, add --binding=<ENVIRONMENT_VARIABLE_NAME>=<ENVIRONMENT_VARIABLE_VALUE> to the wrangler pages dev command:

$ npx wrangler pages dev --binding=<ENVIRONMENT_VARIABLE_NAME>=<ENVIRONMENT_VARIABLE_VALUE>

​​ Secrets

Secrets are a type of binding that allow you to attach encrypted text values to your Pages Function. You cannot see secrets after you set them and can only access secrets programmatically on context.env. Secrets are used for storing sensitive information like API keys and auth tokens.

To add secrets to your Pages project:

  1. Log in to the Cloudflare dashboard and select your account.
  2. In Account Home, select Workers & Pages.
  3. Select your Pages project > select Settings > Environment variables.
  4. Selecting Add variables under Production and/or Preview.
  5. Select Encrypt to create your secret.
  6. Select Save.

You use secrets the same way as environment variables. When setting secrets with Wrangler or in the Cloudflare dashboard, it needs to be done before a deployment that uses those secrets. For more guidance, refer to Environment variables.

​​ Interact with your secrets locally

When developing locally, add secrets by creating a .dev.vars file in the root directory of your Pages project. Then add the following code snippet to .dev.vars:

`.dev.vars`
SECRET_NAME=<SECRET_VALUE>